Errors & Limits

Status codes, error shapes, timeouts, and concurrency guidance for the Agent API

Error shape

Errors before the stream opens are JSON, in Anthropic’s shape:

{ "error": { "type": "not_found_error", "message": "Agent not found in this workspace" } }

Errors after the stream opens arrive as an SSE event on an already-200 response:

event: error
data: {"type":"error","error":{"type":"api_error","message":"…"}}

A 200 status only means the turn started. Always handle error events, and treat a stream that ends without message_stop as a failed turn.

---

Status codes

Status	error.type	Cause	Fix
400	invalid_request_error	Missing body, empty messages, or no user-role text in messages	Send a non-empty messages array with at least one role: "user" entry
401	authentication_error	Missing, unknown, or malformed key	Check the X-Api-Key header
401	—	{"message": "API key has been revoked"}	Create a new key
401	credential error	The agent has no usable LLM credential	Add the agent’s model credential in the workspace
403	permission_error	Viewer role, or writing to a shared conversation you don’t own	Use an Operator+ key; fork the conversation
404	not_found_error	Agent not found in this workspace	Check the agent slug and that the key belongs to the agent’s workspace
404	not_found_error	Conversation not found	The id belongs to another agent, workspace, or user
404	HTML page	Wrong HTTP verb (GET on /v1/messages)	Routes are method-specific — use the documented verb
409	conflict_error	Fork target id already taken	Omit conversation_id on fork, or pick a new one
413	—	Request body over 15 MiB	Reduce attachment size (10 MiB decoded cap)
501	not_implemented	metadata.delivery: "async"	Use webhooks or schedules for background runs

Why a workspace mismatch shows up as 404, not 403

Agent lookup is scoped to the calling key’s workspace, and a miss is reported the same way whether the agent doesn’t exist or lives somewhere you can’t see — so no caller can probe for agent names in other workspaces. If you’re sure the name is right, the key is almost always the problem.

---

Limits and timing

Per-turn ceiling	10 minutes of agent execution
Typical short turn	~10–20 s, dominated by sandbox and agent startup
Attachments	10 files, 10 MiB decoded total, per turn
Request body	15 MiB
Rate limit	None on this endpoint — bound concurrency yourself

A long-running turn that is producing output or doing tool work stays alive; the runtime only cancels a turn that has genuinely lost its network or exceeded the ceiling. A turn cancelled that way keeps its resume pointer, so sending "continue" on the same conversation picks up where it stopped.

Client configuration

• Set generous timeouts. Default HTTP client timeouts (30 s) will cut off normal agent work. Allow at least 10 minutes and read the stream incrementally.
• Disable buffering proxies. Any intermediary that buffers responses breaks streaming. The endpoint sends Cache-Control: no-cache, no-transform.
• Retry on the conversation, not the request. Because a resumed turn appends to durable history, a blind retry of a turn that partially succeeded can double up work. Prefer sending a fresh instruction on the same conversation_id.
• Wait for the resume pointer between back-to-back turns. Sending the next message the moment a stream ends can resume a conversation before its session is recorded, and the agent loses the previous turn’s context silently. See Resuming.

Concurrency

Each conversation runs in one sandbox. Two simultaneous turns on the same conversation_id share it and race on the transcript.

Serialize turns within a conversation; parallelize across conversations. A queue keyed by conversation_id is the simplest correct client design.

---

Observability

Every turn records an execution on the agent — status, duration, and result — with API-key traffic tagged separately from web-UI traffic, so you can filter your integration’s runs on the agent’s activity page. Failed turns keep their error message there, which is usually faster than reconstructing it from the stream.