Error codes

Errors come with a standard HTTP status and a body in the OpenAI API format — the same one compatible SDKs expect.

Error body format

json

{
  "error": {
    "message": "Human-readable description",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}

OpenAI-compatible SDKs parse this body and raise an exception — inspect the status and error.message.

Codes

Status	Meaning	What to do
`400`	Bad Request — invalid body: malformed JSON, missing required field, invalid parameter value.	Check the JSON and parameters (`model`, `messages`). The `error.message` text will say what's wrong.
`401`	Unauthorized — key missing, invalid or revoked.	Check the `Authorization: Bearer cai-...` header. If the key was revoked — create a new one in API keys.
`402`	Payment Required — insufficient balance for the request.	Top up the balance. Request cost — see Pricing.
`403`	Forbidden — this resource or model is not available to your key.	Make sure the model is in the catalog and available (`status` is not "soon").
`404`	Not Found — unknown model or non-existent path.	Check the model name (the `model` field) and the endpoint path — `/v1/chat/completions`, `/v1/embeddings`, etc.
`408` / `504`	Timeout — the provider took too long to respond.	Retry the request. For long responses use streaming (`stream: true`) — so the connection doesn't hang waiting for the whole reply at once.
`429`	Too Many Requests — rate limit exceeded.	Retry with exponential backoff (0.5s, 1s, 2s…). If a `Retry-After` header is present — wait the indicated time.
`500`	Internal Server Error — internal gateway error.	Retry the request. If it reproduces consistently — let us know with the time and model (no key needed).
`502` / `503`	The model provider is temporarily unavailable or overloaded.	Retry with a delay, or temporarily switch to another model from the catalog.

Retrying

Safe to retry on , , , , , — with exponentially growing delay and a bit of jitter, 3–5 attempts. Don't retry , , , , — these are request or account errors that need fixing, not retrying. The official OpenAI and Anthropic SDKs already implement these retries — you don't need to add anything separately.