Errors

Something returned a code you have not seen

Every failure has the same shape:

{"error":{"code":"permission_denied",
          "message":"This token does not have the \"sessions:read\" scope.",
          "request_id":"859ae087"}}

Branch on code, not on the HTTP status and not on the message. The status is what a proxy needs; the code is what your integration needs. Messages are written for people and may be reworded.

request_id is also on the x-request-id header. Quote it when you ask us about a call — it is how we find that exact request in our logs.

Every /v1 response carries x-request-id, not only the failures — a 200, a 202, an SSE stream. The calls worth asking about are often the ones that succeeded and did something surprising, and those need a handle too. Log the header next to whatever your integration records about the call; it costs nothing until the day it is the only thing that helps.

The codes

A 401 also carries WWW-Authenticate: Bearer realm="gobare", error="…" — the standard challenge, so an HTTP client learns the scheme without being configured for it.

The Retry column is also on the wire. Every code marked retryable carries a Retry-After header; the ones marked no carry none, and the absence is the signal — project_limit_exceeded is a 429 and provider_unauthorized is a 502, and neither is a wait. A client that honours Retry-After and gives up without one is doing the right thing on every row below without knowing any of them.

The numbers are a floor on politeness rather than a prediction. Where we can compute the real wait — the rate limiter, the stream ceiling — we send that instead.

Code	Status	Retry	Meaning
invalid_request	400	no	The request is malformed, or a field is wrong. Includes a body over the size ceiling
context_length_exceeded	400	no	The conversation is too long for the model
authentication_error	401	no	No token, or one we do not recognise. A revoked or expired token lands here
permission_denied	403	no	The token is valid and lacks the scope, which the message names
not_found	404	no	No such session, turn, artifact, template — or no such endpoint
method_not_allowed	405	no	The path exists; this verb does not. The Allow header lists the ones that do
conflict	409	maybe	The session is not in a state that allows this. input.steer with no turn running is the common one
queue_full	429	after a wait	This session already holds the maximum queued messages
rate_limit_exceeded	429	after Retry-After	Too many requests, or too many open streams
project_limit_exceeded	429	no	Your organization is at its concurrent-session ceiling. Waiting does not help; delete a session or ask us to raise it
internal_error	500	yes	We broke. The message is deliberately fixed; the real one is in our logs under your request_id
sandbox_error	500	yes	The workspace failed during the operation
workspace_recovery_failed	500	no	A workspace could not be restored. The session needs attention rather than a retry
bridge_incompatible	500	no	The session’s sandbox predates a capability you asked for. Create a new session
provider_error	502	yes	Your model provider failed
provider_unauthorized	502	no	Your model provider rejected the credential. Fix it in the Console
sandbox_unavailable	503	yes	The workspace is not reachable right now
directory_unavailable	503	yes	We could not reach the service that knows what your organization owns

Refusals worth recognising

Several invalid_request refusals exist specifically so a value is never accepted and then ignored. Each names what to do:

Sending	Answer
environment.repo with no GitHub connection on the organization	Connect GitHub in the Console, then create the session again
environment.repo as a URL	Send owner/name; the message shows the corrected form
environment.branch	The branch is reported by the clone, not chosen. Read environment.repo.branch
An unknown agent.approval_mode	Use one of auto, per_step, read_only, plan. It is never defaulted for you
A permission_rules entry with no valid decision	Every rule needs allow, deny or ask
metadata past its ceilings, or a non-string value	Nothing is truncated or coerced; fix the value
A PATCH with no recognised field	Send title, metadata, agent.instructions, agent.approval_mode or agent.permission_rules
agent.instructions longer than 32000 characters	Refused with both numbers. Never truncated — half a set of instructions looks like a model ignoring them
agent.instructions on a workspace older than the feature	bridge_incompatible. Delete the session and create a new one

An environment.profiles id belonging to another organization answers not_found, not permission_denied — an id cannot be probed for existence.

The three 429s

They share a status and recover differently, which is exactly why the code matters more than the status:

• rate_limit_exceeded — you are asking too fast. Retry-After says how long to wait, and honouring it works. See limits.md.
• queue_full — this session is saturated. Wait for its turns to drain, or use another session.
• project_limit_exceeded — you are at the ceiling for concurrent sessions. Retrying never succeeds. Delete something or talk to us.

A client that retries all 429s identically will spin forever on the third.

Internal errors

An unexpected failure is reported as internal_error with a fixed message. Internal errors routinely carry file paths, SQL and provider responses, and none of that belongs in an external response. The real message is in our logs, findable by the request_id you were handed.

If you see one, it is worth reporting.

Errors from outside the API

/v1 always answers JSON in this envelope, including 404 for an unknown path — so a JSON parse failure means you did not reach /v1 at all. Check the host and the /v1 prefix.

A 413 from an intermediate proxy is likewise not us; our own body ceiling answers invalid_request with 400.

Next

• input — what each input event accepts, and when each refusal happens
• troubleshooting — a symptom rather than a code
• limits — the ceilings behind the 429s