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):
{
"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:
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.
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:
{
"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:
{
"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:
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:
{
"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:
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
- Rate limits for the
402and429thresholds your key inherits. - Authentication for what
401means and how to rotate. - Streaming for how errors surface mid-response.