Troubleshooting & FAQ

Common questions and first checks when something is not behaving as expected in AgentWatch.

Do we have to change application code to adopt AgentWatch?

No. The lowest-friction path is changing one environment variable so an existing OpenAI or Anthropic SDK points at AgentWatch with an AgentWatch-issued key — no code changes at all. For estates too large even for that, transparent proxy mode routes existing applications through AgentWatch with no change whatsoever, not even the URL, by mapping provider hostnames to the gateway. Both paths keep full DLP, audit, and budget enforcement.

Does AgentWatch need GPUs?

No. AgentWatch is CPU-only. Model inference happens at the provider or on a customer-hosted inference cluster such as Lifeboat, vLLM, TGI, or Triton — AgentWatch is the governance and observability layer in front of it.

I’m getting 402 responses. What does that mean?

A budget has been exceeded and the gateway is enforcing it rather than alerting. Check which of the four tiers tripped — organization, team, tenant, or user key — since the strictest applicable limit wins. Remedies are to raise the limit, grant a temporary override with an expiry, or wait for the daily or monthly window to reset. The response code is configurable if your clients handle 429 more gracefully.

I’m getting 429 responses. Which limit is it?

Rate limiting applies across many dimensions — model, user, team, organization, API key, application, MCP server, and individual tool — so check the scope in the audit record for the rejected request. AgentWatch deliberately returns 429 with a Retry-After header rather than a server error, so a well-behaved SDK backs off instead of retrying into the wall. The per-scope breach behavior is configurable: fall through to the next-priority provider, return 429, or alert.

DLP is blocking legitimate requests. How do I tune it?

Put the policy in log-only mode first and let it run against real traffic — that produces the false-positive set without disrupting anyone. Then raise the confidence threshold for the noisy category, adjust severity, or add allow-list entries. Detection confidence is configurable per category, and custom recognizers can be added per organization without code changes. Name detection in particular is tuned not to fire on ordinary factual questions.

Requests are failing after a provider incident. What should I check?

Circuit-breaker state, visible in the metrics and the console. When a provider trips its breaker, AgentWatch fails over to the next-priority key or provider in the same model family — so confirm a fallback with the required capabilities is actually configured, and that its keys still authenticate. Per-key efficacy testing probes a key against the live provider to confirm it works and has quota.

An agent’s requests are being refused with a policy message. Why?

That is insider-risk enforcement: the agent’s risk score crossed the configured block threshold, so the request was stopped before reaching the provider. The Enforcement view shows current actor standings, the active policy, and a decision log for every outcome. Enforcement is off by default and only applies once a policy is configured and enabled; thresholds for warn, step-up, and block are all adjustable, and policy changes take effect immediately.

Nothing appears in the dashboards. Is it broken?

Two common causes. First, check whether demo mode is on — it is enabled by default for new installations and shows generated sample data rather than yours; it is toggleable per user and can be disabled globally at install time. Second, if real traffic is expected but absent, confirm applications are actually pointed at the gateway and that their keys are valid, since a misconfigured client typically still reaches its provider directly.

Do upgrades require a migration step?

No. Schema changes are applied and backfilled automatically at boot, so an upgrade is an image swap that keeps the data volume. Multi-instance deployments support zero-downtime rolling upgrades — drain a node, upgrade it, return it to the pool — with in-flight requests preserved through a graceful shutdown window. Documented rollback procedures and a pre-upgrade checklist accompany each release. Keep the data volume: do not remove volumes when bringing the stack down.

How is AgentWatch different from an AI observability platform?

Observability tools record what happened. AgentWatch enforces inline, before the request leaves: a budget breach rejects the request instead of alerting after the money is spent; DLP blocks or redacts before the provider sees the prompt rather than scrubbing a trace afterwards; prompt injection is blocked at the gateway rather than annotated. It also covers surfaces observability tools cannot see at all — unmanaged public AI usage on employee devices, MCP tool calls, and autonomous agents as their own risk class. AgentWatch also exports OpenTelemetry and Prometheus telemetry, so it complements an existing APM rather than replacing it.

Where do I get help?

Contact your Iterate.ai representative with your AgentWatch version, deployment mode (self-hosted, SaaS, hybrid, or air-gapped), the health endpoint output, and the audit record or trace ID for the affected request. Diagnostics endpoints are available for support investigations.

Sources and references

• Enforcement behavior in depth: Governance and cost control.
• Deployment and sizing: Deployment.