Skip to main content

Errors & status codes

Errors from /v1/* endpoints are always JSON in the format of that endpoint’s SDK, and always include a request_id.

Error format

OpenAI-style endpoints (/v1/chat/completions, /v1/responses, /v1/embeddings, /v1/images/*, /v1/videos/generations) use the OpenAI shape:

OpenAI format

{  "error": {    "message": "Invalid API key.",    "type": "authentication_error",    "param": null,    "code": "invalid_api_key"  },  "request_id": "5d0c…"}

/v1/messages and /v1/messages/count_tokens use the Anthropic shape:

Anthropic format

{  "type": "error",  "error": {    "type": "invalid_request_error",    "message": "Missing required field `max_tokens`."  },  "request_id": "5d0c…"}

Handle errors by HTTP status and error.type. The param and code fields are often null and are missing from some errors, so don’t rely on them. The official SDKs turn these errors into the matching exceptions (for example AuthenticationError for 401). The request_id is also sent in the x-request-id header; include it when you contact support.

Unsupported fields

A request field, value, tool type or content type that is not available is never dropped silently: the request is rejected with 400 before it runs, at no cost. The message names what was refused and says why or what to use instead, and on OpenAI-style endpoints error.param names the field. The rules per endpoint are in Chat Completions, Messages and Responses.

400 · /v1/chat/completions

HTTP/1.1 400 Bad Request{  "error": {    "message": "Chat completions for this model do not support the `seed` field: a sampling seed cannot be set for it",    "type": "invalid_request_error",    "param": "seed",    "code": null  },  "request_id": "5d0c…"}

Status codes

Status type Meaning What to do
400invalid_request_errorRejected before the request runs: malformed JSON, a field or value that is not supported for the model, n other than 1, content that is not available (audio, files, server-side tools), max_tokens ≤ 0 or above the model limit, a hold above the per-request maximum, a model called on an endpoint that does not serve it, or a sub-path of /v1/responses. The message names the field and says why; on OpenAI-style endpoints error.param names it too. A request the model provider itself rejects as invalid is also a 400.Fix the request as the error message describes. Don’t retry it unchanged.
401authentication_errorThe API key is missing, wrong, revoked, or belongs to a disabled account. The message is always "Invalid API key."Check the key and the authentication header.
402insufficient_balanceYour available balance is smaller than the hold the request needs. The response includes required_usd_nanos and available_usd_nanos. Token counting answers 402 without those two fields when your balance is empty.Top up, or lower max_tokens.
404not_found_errorA model ID that is unknown or not available to your key ("The model … does not exist or you do not have access to it.", code model_not_found), or an endpoint path that doesn’t exist ("Unknown endpoint …").Copy the model ID from the Models & Pricing page and check your base URL.
408api_errorThe time limit passed before the request reached the model ("Request timed out."), or the model’s upstream timed out before it answered. Nothing is charged.Safe to retry; use streaming for long outputs.
413invalid_request_error
request_too_large (Anthropic)
The request body is larger than 16 MB ("Request body is too large."), or too large for the model.Send a smaller request.
415invalid_request_errorContent-Type is not application/json.Send the Content-Type: application/json header.
422invalid_request_errorValid JSON, but a required field is missing or has the wrong type (for example "Missing required field `max_tokens`." on /v1/messages, or prompt and duration_seconds).Add the fields described in the endpoint’s docs.
422timeout_errorThe request reached the model, but no reply arrived within the time limit (90 seconds to the first response). The message starts with "The upstream provider timed out after the request was sent." The provider may have done part of the work, so you may be charged for the partial usage it reports. The response carries x-should-retry: false, so the OpenAI and Anthropic SDKs do not retry it automatically.Check the Usage page before sending it again. For a long generation set stream to true: a stream only has to start within the time limit, not finish.
429rate_limit_errorEither your API key is over its own limit ("Rate limit exceeded for this API key. Slow down." or "Too many concurrent requests for this API key. Wait for one to finish."), or the model is rate limited upstream on every available route ("Rate limit reached. Please try again later.", with error.code "rate_limit_exceeded" on OpenAI-style endpoints). A Retry-After header may be present.Wait for the number of seconds in Retry-After when it is present, otherwise back off, then retry.
501invalid_request_errorThe requested feature is not implemented.Use an endpoint or feature listed in these docs.
502api_errorThe model could not be reached or could not serve the request on any available route, its reply was unreadable, or an internal error occurred ("The server could not complete this request. Retry later, quoting the request_id if it persists.").Retry later; include the request_id if it keeps happening.
500, 503, 529 and other 5xxapi_errorThe model’s upstream answered with a server error or is overloaded, on every available route ("The server had an error while processing your request.", with error.code "server_error" on OpenAI-style endpoints). A 503 may carry a Retry-After header.Retry with backoff, honouring Retry-After.
503api_errorA temporary problem on our side, not in your request: billing or authentication is briefly unavailable, or the model cannot be served right now. The request is rejected before it runs.Try again later, or pick another model from the Models & Pricing page.

Upstream failures

When a model’s upstream is unreachable, rate limited or failing, the request is sent to another upstream for the same model automatically, as long as nothing has been sent to you and nothing has been charged. An upstream error therefore reaches you only when no available route could serve the request: as 502, or with the upstream’s own 429 or 5xx status. Such an error is not charged and is worth retrying after a pause.

Are errors charged?

  • Every error that happens before the request reaches the provider (400, 401, 402, 404, 413, 415, 422 invalid_request_error, a 429 for your key’s own limit, 501 and 503 above) is free.
  • An official validation error from the provider (HTTP 400) is also free.
  • An error status from the model’s upstream (429, 5xx, or its own timeout) is free: the held funds are released automatically.
  • A timeout before the request reached the provider (408) is free. A timeout after it was sent (422 timeout_error) is charged only for the usage the provider reports, marked Partial.
  • A reply that breaks off part-way (an unreadable reply, or an error in the middle of a stream) is charged only for the usage the provider reported before it failed, marked Partial. If no usage was reported, nothing is charged. See Billing & balance.

Retrying

Retry only 408, 429 and 5xx, with increasing delays (exponential backoff). A 429 or 503 may carry a Retry-After header: a whole number of seconds, at most 60. Wait at least that long before the next attempt; the official SDKs do this for you.

Don’t retry 400, 401, 402, 404 or 422 without changing the request; the result will be the same. A 422 with type timeout_error is different: the request reached the provider and may already be charged, so retrying would pay again. That’s why it is sent with x-should-retry: false, which the official SDKs respect. Check your usage first, then decide.

Time limit: 90 seconds to the first response

A request has to get its first response within 90 seconds: the complete reply without streaming, or the start of the stream with "stream": true. A long generation should therefore be streamed. A request that times out after it was sent to the model provider returns 422 with type timeout_error and the header x-should-retry: false; 408 only means the request never reached the provider (nothing charged, safe to retry). If your code handles timeouts by checking for 408, also handle 422 timeout_error, and don’t retry it blindly.

Start with any balance,
however small.

Create a free accountSign in AI API · pay as you go