Troubleshooting: agent runtime errors

An agent run returns a non-2xx envelope, an SSE stream aborts with an error event, or a conversation shows a failed turn in the Live tab. The error.code in the response tells you which gate fired. This page covers the six codes the agent runtime throws, in the order you will meet them. The full list of platform codes lives in the error reference; this page gives you the fix for each agent code. A typical envelope looks like this — the code is the stable identifier you key on, never the message text:

{
  "error": {
    "code": "AGENT_EXECUTION_TIMEOUT",
    "message": "Agent execution timed out. Please retry.",
    "status": 504
  },
  "meta": {
    "request_id": "req_01HZXK8FJ2",
    "timestamp": "2026-09-09T12:34:05.119Z"
  }
}

Decision table — agent error → fix

Code	HTTP	Cause	Fix
`AGENT_NOT_CONFIGURED`	422	Deploy or run attempted on an agent with no `system_prompt` set.	Set a system prompt on the agent (`PATCH /agents/:id` with `system_prompt`), then re-deploy. New agents start in `draft` — fill in the prompt before channel deployment.
`INVALID_MODEL`	422	The agent’s `model` id is not in the supported allowlist — usually a legacy or misspelled id persisted on the agent.	Pick a supported id from model selection and PATCH the agent. Known retired ids are re-mapped to their served replacement on save; a genuinely unknown id 422s at write time, not at run time.
`AGENT_RESPONSE_INVALID`	502	The run completed but the response payload could not be parsed — the runtime returned malformed JSON for the turn.	Safe to retry once (the same input often succeeds). If it recurs on the same agent, shorten/clamp the prompt or attached tools — oversized outputs are the common cause — and check the failing turn in the Live tab.
`LLM_PROVIDER_ERROR`	502	Anthropic upstream failed — the model-call threw (overload, internal error, provider-side fault) before the turn completed.	Check the status page, retry with backoff. If sustained on one agent, pin a fallback model via model selection where your fallback policy lives.
`AGENT_ERROR`	502	Catch-all: the runtime connection failed, or the upstream returned an error envelope without a narrower code.	Read the accompanying `message` first — the platform propagates the runtime’s structured envelope when one was sent. If `message` is empty after this page, collect the `request_id` from `meta` and escalate.
`AGENT_EXECUTION_TIMEOUT`	504	The turn exceeded the execution ceiling — the default 30-second platform ceiling, or your per-agent `config.latency_budget.turn_ms` override (1 000–180 000 ms). A runaway tool-call loop is the usual cause.	Inspect the failing conversation in the Live tab and check the agent’s tool chain for loops. Either fix the looping tool, or raise the ceiling with `latency_budget` (see cost controls for the adjacent iteration caps).

Do not retry the deterministic codes

Three of these codes re-fail deterministically — a retry re-runs the same gate and returns the same code:

AGENT_NOT_CONFIGURED — the prompt is still missing until you write one.
INVALID_MODEL — the model id is still illegal until you pick a supported one.
A capped or gated run (cost caps, guardrails) — same input, same gate.

Retry only the transient ones: LLM_PROVIDER_ERROR (provider blip), AGENT_RESPONSE_INVALID (occasionally), and AGENT_EXECUTION_TIMEOUT after you have removed the loop cause — otherwise the retry burns the 30-second ceiling again. Live-stream clients key on the same sanitised code set: the SSE path maps upstream failures to stable machine codes (LLM_RATE_LIMITED, LLM_OVERLOADED, AGENT_EXECUTION_TIMEOUT, …) so your client can branch on code, not on a message string.

Distinguish timeout from runaway loops

AGENT_EXECUTION_TIMEOUT has two very different causes and they pair with different fixes:

A genuinely slow agent — a deep-research prompt with a legal 30 s budget. Fix: set config.latency_budget.turn_ms (up to 180 000 ms) on the agent and retry.
A runaway tool loop — the agent chains the same tool until the ceiling trips. Fix: inspect the run in the Live tab, find the repeating tool call, and correct the tool or the prompt that re-invokes it. Raising the ceiling hides the loop rather than fixing it; the parallel tool_loop_limit cap exists for that case.

Delete and archive guards

A DELETE /agents/:id or a write against an archived agent fails with one of the codes below. These are deterministic gates, not runtime faults — the runbook is short: clear the reference that blocked you, then repeat the call.

Code	HTTP	Cause	Fix
`AGENT_REFERENCED_BY_SQUAD`	409	The agent is the classifier of one or more squads. The classifier slot hard-restricts deletion, so the delete is refused. The response message names up to five blocking squads (the first five, with a “+N more” suffix beyond that).	Remove the agent from each named squad (`PATCH /squads/:id` to point the classifier slot at a different agent, or delete the squad), then re-run the delete.
`AGENT_REFERENCED_BY_CHILD_ROWS`	409	A race-time backstop: another row came to reference the agent between the pre-check and the delete, so the database constraint fired anyway.	Same remedy — treat it as a squads/references condition: clear the references (`AGENT_REFERENCED_BY_SQUAD` names the common one), then retry the delete.
`AGENT_ARCHIVED`	400	You placed an outbound call or wrote to an agent whose `status` is `archived`. Archived is a read-heavy state — origination and mutation are refused.	Unarchive the agent (`PATCH /agents/:id` with `status` set back to `active`), then repeat the call.
`AGENT_REQUIRED`	401	A dial or origination endpoint that requires a named human operator was called with server credentials only — no authenticated agent on the request.	Sign in as an agent and call from a user session, not from a server-to-server credential.

Two adjacent codes are documented where they belong rather than re-explained here:

Code	Where to look
`AGENT_INVOCATION_QUOTA_EXCEEDED` (429, daily quota)	Agents overview — invocation throttles
`AGENT_INVOCATION_RATE_LIMIT_EXCEEDED` (429, per-minute)	Agents overview — invocation throttles

Child rows to clear first

Delete refuses while any of these still point at the agent. Walk them in order:

Active conversations — the delete pre-check returns a 409 while the agent owns active conversations. Let them finish or close them.
Squads where the agent is the classifier — the hard stop that raises AGENT_REFERENCED_BY_SQUAD. Re-point the classifier slot or delete the squad.
Squads where the agent is the fallback — the fallback slot would auto-null on delete, but the pre-check reports it ahead of time so you see the full impact before confirming.
Anything else referencing the agent — if a row is created in the gap between the pre-check and the delete, the backstop raises AGENT_REFERENCED_BY_CHILD_ROWS. Clear the new reference and retry.

Error samples

AGENT_REFERENCED_BY_SQUAD — the message lists the blocking squads:

{
  "error": {
    "code": "AGENT_REFERENCED_BY_SQUAD",
    "message": "Cannot delete agent: still used as classifier by squad(s): Frontdoor triage, Overflow routing (+1 more). Remove the agent from these squads first.",
    "status": 409
  },
  "meta": {
    "request_id": "req_01J03VXB3M",
    "timestamp": "2026-09-09T12:59:44.210Z"
  }
}

AGENT_REFERENCED_BY_CHILD_ROWS — the race-time backstop, same 409:

{
  "error": {
    "code": "AGENT_REFERENCED_BY_CHILD_ROWS",
    "message": "Cannot delete agent: still referenced by other rows. Remove the references first and retry.",
    "status": 409
  },
  "meta": {
    "request_id": "req_01J03W1P7R",
    "timestamp": "2026-09-09T12:59:46.418Z"
  }
}

AGENT_ARCHIVED:

{
  "error": {
    "code": "AGENT_ARCHIVED",
    "message": "Voice agent agt_9f2c4d7e is archived. Unarchive it before placing outbound calls.",
    "status": 400
  },
  "meta": {
    "request_id": "req_01J03W4K9T",
    "timestamp": "2026-09-09T13:01:12.055Z"
  }
}

AGENT_REQUIRED:

{
  "error": {
    "code": "AGENT_REQUIRED",
    "message": "Preview dial requires an authenticated agent. Internal HMAC callers cannot originate dial legs on behalf of an operator.",
    "status": 401
  },
  "meta": {
    "request_id": "req_01J03W9Q2V",
    "timestamp": "2026-09-09T13:02:33.781Z"
  }
}

Do not force it through

Every one of these guards is deterministic. A force-delete attempt — sending the same body with an added force: true, or issuing the raw delete from a client — returns the identical 409/422 on every retry; there is no force flag the API honors. Clearing the references is the only path through. Escalate only if the guard keeps firing after the response’s own list is empty — e.g. AGENT_REFERENCED_BY_SQUAD still 409s when every squad it named has been re-pointed. That indicates a stale pre-check, not operator error; include the request_id from meta, the agent id, and the squad ids you detached.

When to escalate

Escalate to support when:

The same agent returns AGENT_ERROR with an empty or opaque message and you have ruled out the table above.
LLM_PROVIDER_ERROR persists after the status page reports all operational.
AGENT_EXECUTION_TIMEOUT fires on a turn with no tool calls at all — that should not reach the ceiling.

Include the request_id from the meta block of the failing response, the agent id, and the conversation id. The request id threads through the chat, stream, and invoke paths, so support can pull the executor-side trace without a back-and-forth.

Reference

Troubleshooting: agent runtime errors

Troubleshooting: agent runtime errors

Decision table — agent error → fix

Do not retry the deterministic codes

Distinguish timeout from runaway loops

Delete and archive guards

Child rows to clear first

Error samples

Do not force it through

When to escalate

See also

​Troubleshooting: agent runtime errors

​Decision table — agent error → fix

​Do not retry the deterministic codes

​Distinguish timeout from runaway loops

​Delete and archive guards

​Child rows to clear first

​Error samples

​Do not force it through

​When to escalate

​See also

Troubleshooting: agent runtime errors

Decision table — agent error → fix

Do not retry the deterministic codes

Distinguish timeout from runaway loops

Delete and archive guards

Child rows to clear first

Error samples

Do not force it through

When to escalate

See also