Error codes
Every error is a JSON body in the OpenAI error format. Branch on code, which is stable; message is for people and can change.
JSON
{
"error": {
"message": "Your balance is insufficient for this request.",
"type": "insufficient_balance_error",
"param": null,
"code": "insufficient_balance"
}
}param names the request field that caused the error when there is one, for example messages or max_tokens, and is null otherwise. The OpenAI SDKs raise these as exceptions (BadRequestError, AuthenticationError, RateLimitError and so on) with the body attached.
All codes#
| HTTP status | Code | Type | Description |
|---|---|---|---|
| 400 | invalid_json | invalid_request_error | The request body is not valid JSON. |
| 400 | invalid_request | invalid_request_error | The request body is malformed or contains an invalid value. |
| 400 | unsupported_parameter | invalid_request_error | The parameter needs server-side state we never keep (for example previous_response_id or background on /v1/responses). |
| 400 | unsupported_content | invalid_request_error | The model does not accept this content type (for example, image input). |
| 400 | image_url_not_supported | invalid_request_error | Image URLs are not fetched. Send the image inline as a base64 data URL (data:image/png|jpeg|webp|gif;base64,...). |
| 400 | context_length_exceeded | invalid_request_error | The prompt and requested output do not fit in the model's context window. |
| 400 | invalid_support_subject | invalid_request_error | The support request subject is empty or too long. |
| 400 | invalid_support_body | invalid_request_error | The support request message is empty or too long. |
| 401 | invalid_api_key | authentication_error | The API key is missing, malformed or revoked. |
| 401 | authentication_required | authentication_error | The panel session is missing or expired. |
| 403 | origin_not_allowed | permission_error | The request came from an origin that is not allowed to call the panel API. |
| 402 | insufficient_balance | insufficient_balance_error | The project balance cannot cover the request's reservation. |
| 404 | model_not_found | not_found_error | No active model has this id. |
| 413 | request_too_large | invalid_request_error | The request body exceeds the size limit. |
| 429 | rate_limit_exceeded | rate_limit_error | The project sent too many requests per minute. |
| 429 | concurrency_limit | rate_limit_error | The project has too many requests in flight. |
| 429 | model_capacity | rate_limit_error | The model is temporarily at capacity. Retry after the Retry-After interval. |
| 429 | support_rate_limited | rate_limit_error | The account opened too many support requests. Retry after the Retry-After interval. |
| 500 | internal_error | api_error | An unexpected error occurred on our side. |
| 502 | upstream_error | api_error | The model failed to produce a response. |
| 503 | model_unavailable | api_error | The model is temporarily unavailable. |
| 504 | upstream_timeout | api_error | The model did not respond in time. |
Causes and fixes#
| Code | Cause and solution |
|---|---|
| 400 Invalid request | Cause: the body is not valid JSON (invalid_json), a field has a wrong type or value (invalid_request), or the prompt plus max_tokens is longer than the context window (context_length_exceeded). Solution: check param and message, compare the request with Chat completions, and shorten the history or lower max_tokens for context errors. |
| 400 Unsupported content | Cause: the model does not accept a part of the message, usually an image sent to a text-only model (unsupported_content), or an image was given as a web URL (image_url_not_supported). Solution: pick a model with Vision in Models & pricing and send images inline as base64 data URLs. |
| 401 Authentication failed | Cause: the Authorization header is missing, the key is mistyped, or the key was revoked (invalid_api_key). Solution: send Authorization: Bearer <key> and check the key on the API keys page; create a new one if needed. |
| 402 Insufficient balance | Cause: your available balance cannot cover the hold for this request (insufficient_balance). The hold counts up to one token per byte of prompt text plus max_tokens of output, and is settled to actual usage. Solution: add credit on the Billing page, or lower max_tokens so the hold is smaller. See Deduction rules. |
| 403 Forbidden | Cause: a browser request to the dashboard API from another site (origin_not_allowed). Solution: call the API from your server with an API key. |
| 404 Not found | Cause: the model value does not match an active model (model_not_found). Solution: copy the id from GET /v1/models; ids are case sensitive. |
| 413 Request too large | Cause: the body is over 8 MB, or one image is over 5 MB (request_too_large). Solution: compress or resize images, and trim long histories. |
| 429 Too many requests | Cause: your project hit its per-minute or concurrency limit (rate_limit_exceeded, concurrency_limit), or the model is at capacity (model_capacity). Solution: wait for the Retry-After interval and retry with backoff. See Rate limits. |
| 500 Server error | Cause: an unexpected error on our side (internal_error). Solution: retry after a short wait. If it keeps happening, contact us with the time of the request. |
| 502 Upstream error | Cause: the model failed while producing the response (upstream_error). Solution: retry. Nothing is billed if no content was returned. |
| 503 Model unavailable | Cause: the model is temporarily offline (model_unavailable). Solution: retry later, or switch to another model. |
| 504 Timeout | Cause: the model did not answer in time (upstream_timeout). Solution: use stream: true for long answers, or lower max_tokens. |
Errors during a stream#
Once a streamed response has started, the HTTP status is already 200. If the model fails after that point, the API sends one more data: event that holds the usual error body (for example upstream_error or upstream_timeout) and closes the stream without data: [DONE]. The content you received before the error is billed. Treat a stream that ends without [DONE] as incomplete; the OpenAI SDKs raise an exception for the error event.
Retry or not#
- Retry with backoff: 429, 500, 502, 503, 504.
- Do not retry unchanged: 400, 401, 402, 403, 404, 413. The same request fails the same way until you fix it.