Error codes

Every endpoint documents the exact responses it returns. This page covers the error shapes and the status codes you see across the API.

Error shapes

The shape depends on the surface: Speech, LLM, and unified endpoints return a problem object. title and status are always present; detail adds context when available.

{
  "title": "Unauthorized",
  "status": 401,
  "detail": "No Authorization Header"
}

The account API returns a short envelope:

{ "error": "API key id not found" }

WebSocket sessions send an error frame with a machine-readable code and a message:

{ "type": "error", "code": "auth_error", "message": "Invalid or expired API key" }

Common WebSocket codes are auth_error, config_error, rate_limit, and provider_error.

Status codes

Status	Meaning	What to do
`400`	Bad request. The body or parameters are malformed.	Fix the request and resend.
`401`	Missing or invalid API key.	Check the `Authorization` header. See Authentication.
`402`	Insufficient credit or payment required.	Top up the account or check billing.
`403`	The key is valid but not allowed to use this resource.	Confirm the project has access.
`404`	The route or model does not exist.	Check the path and model code.
`409`	Conflict with the current state of the resource.	Reconcile and retry.
`413`	Payload too large.	Send a smaller request.
`415`	Unsupported media type.	Set a supported `Content-Type`.
`422`	Validation failed.	Correct the fields named in the response.
`429`	Rate limited.	Back off and retry. See Rate limits.
`500`	Server error.	Retry, and contact support if it persists.
`502`, `503`	Upstream or service unavailable.	Retry with backoff. On the agents control plane, `503` can mean a dependency is preparing, so wait for the `Retry-After` header.

Speech to text

Context Router (LLM)

Text to speech

Agents

Unified API

Metadata API

Error shapes

Status codes

​Error shapes

​Status codes

Error shapes

Status codes