Errors and retries

Each non-success response uses this envelope:

{
  "error": {
    "message": "Human-readable explanation.",
    "type": "invalid_request_error",
    "code": "invalid_json"
  }
}

Developer routes use these error types:

invalid_request_error
authentication_error
permission_error
rate_limit_error
api_error
service_unavailable_error

Status codes

Status	Meaning
`400`	Invalid JSON or multipart data, an unsupported file type, a too-large file on `POST /api/developers/v1/files`, more than 10 files in one upload, an invalid field value, an unsupported tool request, or an invalid structured-output configuration.
`401`	The API key is missing, invalid, revoked, or not authorized.
`403`	The key is suspended, the account cannot use the Developer API, or the key lacks the required scope.
`404`	The referenced run, job, tool, chat, project, file, artifact, video, or transcript is not available to this account.
`409`	The addressed chat is busy, the chat and project conflict, a retired chat id was reused, or a tool submit’s `Idempotency-Key` was first used in another chat.
`413`	An Agent Run upload is too large: one file is over 100 MB, or the whole request is too large (`attachment_too_large`). On MCP, a request body over 150 MB returns `request_too_large`.
`429`	A rate limit, a wallet without room for a new hold, an exhausted per-key budget, exhausted plan usage, or too many active runs for your account at once. Read the response code to distinguish them.
`500`	An unexpected server failure.
`502`	A gateway received an invalid upstream response before the application formed a normal result. Treat it as transient.
`503`	The agent runtime failed or timed out, a dependency or brain is briefly unavailable, or the chat workspace is briefly busy. A workspace-busy response includes `Retry-After: 5`.
`504`	A gateway timed out before the application formed a normal result. The gateway in front of the API closes a connection after 120 seconds without a response. The original run or job may still be running and billed. If the request carried an `Idempotency-Key`, retry with the same key on the same UTC day to get the original run or job back.

Rate-limit responses use rate_limit_error as the error type and include a more specific code. Rate limits lists the request-limit codes. Other 429 codes include:

api_wallet_exhausted
api_key_budget_exhausted
runtime_capacity_busy when the service is near its limit and your account already holds its share of active runs. There is no fixed per-account cap: while capacity is free, your account can run more. Higher plans get a larger share when capacity is contended. The response always includes Retry-After: 5.
monthly_usage_limit_reached for standard member-account MCP plan usage. Contracted partner accounts can have account-specific billing terms.
feedback_rate_limited when the account already sent 60 feedback reports in the last hour. The response includes Retry-After.

A scope restriction returns 403 api_key_scope_forbidden. Common 409 codes include agent_run_rejected (the Agent Run’s chat is busy; the body can include a top-level activeRunId, the UUID of the turn holding the chat), chat_project_mismatch, chat_id_retired, and, for tool submits only, idempotency_conflict. For a busy chat, wait for the blocking run to finish or address a separate chat. A 503 brain_unavailable response means the brain is briefly unavailable. Retry later. It uses the service_unavailable_error type. A 503 workspace_busy response uses the rate_limit_error type and includes Retry-After: 5. A 503 api_wallet_reconciliation_required response is a billing review hold for requests billed to the API wallet. A model receipt lacks billable token counts. Contact support; adding credit does not resolve the hold. Do not retry the request until support resolves the billing review. When the agent runtime fails or times out, a request that reaches it, such as an Agent Run start or cancel, returns 503 with runtime_unavailable, runtime_timeout, or runtime_invalid_response. The work may have started. Check the chat or the run status, or retry a start with the same Idempotency-Key. A load balancer can still return 502 or 504 before the application answers.

Agent Run error codes

POST /api/developers/v1/runs can return these codes in addition to the shared codes above.

Status	Code	Cause
`400`	`message_required`	`message` is missing or empty.
`400`	`invalid_chat`	`chat` is not a valid chat reference.
`400`	`invalid_project`	`project` is not a valid project reference.
`400`	`invalid_sync`	`sync` is not a boolean.
`400`	`invalid_on_busy`	`on_busy` is not `"reject"`.
`400`	`invalid_output_config`	`output_config` breaks a structured-output rule.
`400`	`invalid_json`	The body, or the multipart `payload` field, is not a JSON object.
`400`	`invalid_multipart`	The multipart body cannot be read.
`400`	`invalid_idempotency_key`	`Idempotency-Key` is not 1–128 characters of letters, digits, `_`, `.`, `:`, or `-`.
`400`	`too_many_attachments`	The request carries more than 10 files.
`400`	`unsupported_attachment`	A file type is not supported. Audio and video files are rejected.
`404`	`chat_not_found`	`chat` names a chat this account cannot access.
`404`	`project_not_found`	`project` names a project that does not exist or that this account cannot access.
`409`	`agent_run_rejected`	The chat already has an active turn.
`413`	`attachment_too_large`	A file is over 100 MB, or the whole request is too large.

GET /api/developers/v1/runs/{run_id}, GET /api/developers/v1/runs/{run_id}/events, and POST /api/developers/v1/runs/{run_id}/cancel return 400 invalid_run_id for a malformed run id and 404 run_not_found when this account has no run with that id. A run that fails after it starts reports why in last_error. budget_limited means the run reached the runtime’s limit of 1,500 model steps without finishing. Such a run is not billed.

Retry boundaries

Retry transient infrastructure failures. Do not retry malformed requests, authentication failures, permission failures, or attachment-size errors without changing the request or credentials. Honor Retry-After on 429 and 503. Use the returned effective limits and reset time to tune concurrency. The TypeScript SDK retries requests that are safe to repeat: reads, cancellations, file uploads, event-stream reconnects, and submissions that carry an idempotency key (except research_shortform). It retries on network failures and 408, 429, 500, 502, 503, and 504, honors a Retry-After of up to 60 seconds, and makes at most two retries by default. It never creates an idempotency key for you. Do not blindly retry a run or tool submission without an Idempotency-Key. Use the same key and address so the server can return the original accepted work.

Agent Run and ask_stefanbrain keys deduplicate for the rest of the same UTC day.
Supported asynchronous submit tools deduplicate inside the resolved chat and family during the UTC-day window.
research_shortform is not idempotent.

A keyed retry is still a new request. It counts against rate limits and must pass the same wallet, key-budget, or plan-usage check as new work, so a wallet without room for a new hold can refuse it with 429 api_wallet_exhausted. The server also validates the request body before it looks up the key. When the key matches, the retry answers at once. An Agent Run retry returns the 202 handle while the run is active, or the run’s final status after it ends. A tool submit retry returns the original job’s 202 envelope with the same job_id. Run and job polling does not consume standard request limits.

Tool and job operations can return HTTP 200 with is_error: true. Check the envelope instead of treating every 200 as a successful outcome.

When is_error is true, error.code classifies the tool failure and error.message gives the readable reason. The original content blocks remain in content. For run failures, read output and last_error. For structured-output runs, structured_output is null unless the run completed and its final text is a JSON object. For job failures, inspect the top-level status, is_error, and error, then the family-specific fields in data. See Rate limits and Pricing for the controls behind 429 responses.

Stuck? Send feedback

When an error does not say how to fix the request, or the API cannot do what you need, report it with POST /api/developers/v1/feedback. MCP clients call send_feedback. Include the endpoint or tool, the error code, and the run or chat id. Reports are free, and the StefanBrain team reads every report and replies. See Agent feedback.

Get started

Build with StefanBrain

Operate safely

REST API reference

Status codes

Agent Run error codes

Retry boundaries

Stuck? Send feedback

​Status codes

​Agent Run error codes

​Retry boundaries

​Stuck? Send feedback

Status codes

Agent Run error codes

Retry boundaries

Stuck? Send feedback