Get API key

Errors

View as Markdown

HTTP status codes, error envelopes on each API, and retry guidance.

The API returns standard HTTP status codes. Error bodies use OpenAI's format, except on the Messages API, which uses Anthropic's (see Messages API below):

JSON
{
  "error": {
    "message": "Human-readable description",
    "type": "<category>",
    "code": "<machine-readable>"
  }
}

The Model servers API, the Workspaces API and the Kubernetes API have their own error formats.

Common status codes

Code Meaning What to do
200 Success -
400 Bad request: malformed JSON, unknown field, value out of range, exceeds context window Fix the request; check supported_parameters for the model
401 Authentication failed: key missing, malformed, revoked, or expired Check the Authorization header, or create a new key
402 Budget exhausted: your key or org spend has reached its cap Raise the key cap on the API Keys page, or ask your org admin
403 Forbidden: the key may not call this endpoint, your org has no access to this external provider model, or the request came from an IP address your IP rules don't allow Call from an allowed address, or ask your org admin for access
404 Unknown endpoint, or a model id that doesn't exist or that your org can't use Check the path; check /v1/models
413 Payload too large: the body is over the endpoint's cap (64 MB for chat completions and file uploads, 32 MB for the Responses API, 75 MB for audio uploads, 10 MB for most other endpoints) Shorten or split
429 Rate limited: too many requests per minute on this key Back off with exponential delay
5xx Server error: timeout, memory limit, transient failure Retry with exponential backoff; switch model if it persists

Retry strategy

Retry 429 and 5xx. Don't retry other 4xx codes: they'll fail the same way.

  • Use exponential backoff with jitter, starting at about 1s and capped at about 30s.
  • Stop after 3 to 5 retries and surface the final error.
  • For 429, send fewer requests at once on each key, or spread them across keys.

Streaming errors

An error before the stream starts returns a normal JSON error body with the matching status code.

An error mid-stream arrives as an SSE chunk with an error field when the API can still send one:

Text
data: {"id": "chatcmpl-...", "object": "chat.completion.chunk", "model": "...", "choices": [], "error": {"message": "...", "type": "server_error", "code": "provider_stream_failed"}}

Don't use [DONE] to tell success from failure. An error chunk can be followed by [DONE], and if the connection to the model drops, the stream can end with neither. Check each chunk for error, and treat a stream that ends without a finish_reason as incomplete. A cut stream can also end with finish_reason: "length" and [DONE] and no error. So a length finish means the answer stopped early, either at your token limit or because the stream was cut.

Tip

Base retry and branching logic on error.code, the stable field, and on error.type. error.message is written for people and may change between releases.

Error codes

Code Meaning
budget_exceeded Key or org budget is exhausted
rate_limit_exceeded Too many requests per minute
timeout Model didn't respond in time (mid-stream chunks; see above)
context_length_exceeded The prompt does not fit the model's context window together with max_output_tokens, on the Responses API

Errors relayed from the model

When the model itself rejects a request, most often because the prompt is longer than the context window, the API passes the model's error through unchanged. Then code is the HTTP status as a number, not one of the strings above, and type is the model's own:

JSON
{
  "error": {
    "message": "This model's maximum context length is 262144 tokens. However, you requested 4 output tokens and your prompt contains at least 262141 input tokens...",
    "type": "BadRequestError",
    "param": "input_tokens",
    "code": 400
  }
}

For these errors, branch on the HTTP status, and check the type of code before you treat it as a string. The Responses API rewrites a context overflow as context_length_exceeded: see Responses API.

Messages API

Requests to /v1/messages*, and any request with an anthropic-version header, get errors in Anthropic's format, so the Anthropic SDKs raise their usual typed exceptions:

JSON
{
  "type": "error",
  "error": { "type": "rate_limit_error", "message": "Human-readable description" },
  "request_id": "6f5c..."
}

The same id is in the request-id response header.

Status error.type Meaning Retry?
400 invalid_request_error Malformed request, missing max_tokens, unsupported content such as a PDF No
401 authentication_error Key missing, malformed, revoked, or expired No
402 billing_error Key or org budget exhausted No
403 permission_error The key may not use this endpoint or external provider model, or the request came from an IP address the IP rules don't allow No
404 not_found_error Unknown model or one your org can't use, or an unknown file, batch, or path No
409 conflict_error The object is not in a state that allows this, such as results of a running batch No
413 request_too_large Body over 32 MB (64 MB to create a message batch) No
429 rate_limit_error Too many requests per minute; retry-after says how long to wait Yes
500 api_error Unexpected server error Yes
504 timeout_error The model did not answer in time Yes
529 overloaded_error Capacity is full right now Yes

A prompt longer than the model's context window returns 400 with a message that starts prompt is too long. Clients such as Claude Code look for that wording to compact a conversation.

Mid-stream, an error arrives as an error event, and the stream closes without a message_delta, so a cut-off answer never looks complete:

Text
event: error
data: {"type":"error","error":{"type":"api_error","message":"the model stream ended before the turn finished"}}

The same event, with the message the model stream interleaved a tool call with other output, ends a stream if the model goes back to a tool call after starting other output. That call's tool_use block has already stopped with only part of its input. Don't run it: retry the request.

The Anthropic SDKs retry 408, 409, 429, 5xx and 529 on their own, with backoff. Retrying can't fix a 409, so for that code the SDK's retries only delay the error.

Responses API

Requests to /v1/responses get errors in OpenAI's format, with the status codes above. Anything the endpoint refuses, such as previous_response_id, custom tools or file input, returns 400 with type invalid_request_error and a message saying what to send instead. See Responses API → Errors.

A prompt that does not fit the model's context window together with max_output_tokens returns 400 with code context_length_exceeded. Responses clients look for that code to compact a conversation:

JSON
{
  "error": {
    "code": "context_length_exceeded",
    "message": "This model's maximum context length is 262144 tokens. However, you requested 262000 output tokens and your prompt contains at least 145 input tokens, ...",
    "param": null,
    "type": "invalid_request_error"
  }
}

A 429 with type server_capacity and code too_many_requests means too much is in flight for the key. With tools and a text.format on the request, it can also mean your organization or the whole service has too much in flight. Such a request's final answer may have to be generated again: see With tools on offer. Nothing ran, unless the refused request was the second pass of an answer being generated again. Retry after the 60 seconds in the retry-after header.

Mid-stream, an error arrives as a response.failed event, and the stream closes without response.completed. The event's response has status: "failed" and an error with a code and a message. A context overflow on a stream arrives this way too, with code context_length_exceeded and HTTP status 200:

Text
event: response.failed
data: {"type":"response.failed","sequence_number":2,"response":{"id":"resp_05d3e0e0ca7f4621bc90251310cf3bad","object":"response","status":"failed","error":{"code":"context_length_exceeded","message":"This model's maximum context length is 262144 tokens. ..."},...}}

When a request looks stuck

  • Most often, a proxy between you and the API is buffering a streamed response. See Streaming.
  • Otherwise, check the model's status. A model in maintenance is dropped from GET /v1/models.

Where next