DocsGet started
Errors and rate limits
HTTP status codes, the error bodies of the OpenAI and Anthropic formats, retries, keepalives and timeouts.
Error bodies
OpenAI-format endpoints (/v1/chat/completions, /v1/responses, …) answer errors like this:
JSON
{ "error": { "message": "Invalid or missing API key", "type": "invalid_request_error", "param": null, "code": null } }The Anthropic endpoint (/v1/messages) uses Anthropic's shape:
JSON
{ "type": "error", "error": { "type": "authentication_error", "message": "Invalid or missing API key" } }Status codes
| Status | OpenAI type | Anthropic type | What happened | What to do |
|---|---|---|---|---|
| 400 | invalid_request_error | invalid_request_error | The body is not valid JSON, or the request does not fit the model (for example the prompt is too long) | Fix the request. A too-long prompt reads "prompt is too long: N tokens > M maximum" on /v1/messages |
| 401 | invalid_request_error | authentication_error | The key is missing, wrong or revoked | Check the header and the key |
| 404 | model_not_found | not_found_error | Several of your instances run different models and none matches model | Send one of the listed model ids, or X-Instance-Id |
| 413 | request_too_large | The body is over the limit (64 MiB for chat) | Send less, or upload images by URL | |
| 429 | rate_limit_exceeded | rate_limit_error | Over the key's requests per minute | Wait for Retry-After seconds |
| 502 | upstream_error | api_error | Your instance did not answer | Retry; check the instance page if it repeats |
| 503 | service_unavailable | overloaded_error | No instance is running, or it is still starting (the message says which step it is on) | Deploy, or wait for Ready; Retry-After: 30 is sent while it starts |
Retries
Retry 429, 502 and 503 with backoff, honouring Retry-After. Most SDKs and agents already do. Do not retry 400 and 401 without changing the request.
Long requests and keepalives
Your instance may think for minutes before the first token. So that proxies do not cut the connection:
- Streaming responses get keepalive comments (
: keepalive) in the OpenAI format andpingevents in the Anthropic format while the model prefills. - Non-streaming responses that take long start with HTTP 200 early and send whitespace until the JSON is ready. If the instance fails after that, the error arrives as the JSON body of that 200 response.
Prefer streaming for anything longer than a few seconds. A single request can run for up to 15 minutes.