Errors
The error shape, every status code and code, and which ones to retry.
Errors
Errors use the OpenAI shape: { "error": { "message", "type", "code" } }.
| Status | Meaning |
|---|---|
| 400 | Invalid JSON or parameters. Codes: invalid_messages, max_tokens_exceeded, invalid_reasoning_effort, context_length_exceeded (the prompt plus max_tokens does not fit the context), request_rejected (any other parameter the model refused). |
| 400 | A plan key called a model its plan does not include (model_not_in_plan). Use a pay-as-you-go key for that model. |
| 401 | Missing or invalid API key. |
| 402 | Your balance is empty (insufficient_credits), this API key reached the spend limit set on it in the dashboard (key_spend_limit_reached), or a plan key's renewal payment failed (plan_payment_failed: update your card). |
| 403 | A plan key whose plan has ended (plan_ended): resubscribe, or use a pay-as-you-go key. |
| 404 | Unknown model id. List valid ids with GET /models. |
| 429 | A rate limit was crossed or the model is temporarily at capacity. Wait for Retry-After, then retry with backoff. |
| 502, 503, 504 | The model is temporarily unavailable or did not respond in time. Retry with backoff and quote the x-request-id header when contacting support. |
Objects
The Error object
| Field | Type | Required | Description |
|---|---|---|---|
error | object | Yes | |
error.message | string | Yes | |
error.type | string | Yes | Example: invalid_request_error, rate_limit_error, api_error. |
error.code | string or null | No | Example: model_not_found, context_length_exceeded, max_tokens_exceeded, rate_limit_exceeded, insufficient_credits, key_spend_limit_reached, model_not_in_plan, plan_payment_failed, plan_ended. |
More of the API reference
- API reference: base URLs, authentication and a first request.
- Chat Completions: POST /v1/chat/completions: the OpenAI Chat Completions format, streamed or not, with reasoning and tools.
- Responses: POST /v1/responses: the OpenAI Responses format with stored state, background runs and enforced tool rules.
- Conversations: Keep the turns of a Responses conversation on our side and continue it by id.
- Prompts: Save instructions, messages and settings once, then use them by id in the Responses API.
- Anthropic Messages: POST /anthropic/v1/messages: the Anthropic Messages format, for Claude Code and Anthropic SDKs.
- Models and pricing: Model ids, prices per 1M tokens, context windows, output limits, versions and the live catalog endpoint.
- Batch: Upload a JSONL file of chat completions, create a batch and collect the results when it finishes.
- Rate limits: Requests and tokens per minute, how a 429 tells you when to retry, and how to get more.
- Data retention: What is stored, for how long, how to delete it, and zero data retention.
- Interactive reference: try every endpoint in the browser.
- OpenAPI document: the whole API as OpenAPI 3.1.
This page as Markdown: /docs/errors.md