ewpireErrors
Errors come back in the OpenAI format, with a status that tells you whether to retry.
Every error has the OpenAI shape, so the official SDKs raise their usual exceptions. Messages never name an upstream provider.
JSON
{
"error": {
"message": "The parameter `stop` is not supported.",
"type": "invalid_request_error",
"param": "stop",
"code": "unsupported_parameter"
}
}Codes
| Status | code | What happened | Retry? |
|---|---|---|---|
| 400 | invalid_request, invalid_json | The body is not a valid request. param names the field. | No, fix the request. |
| 400 | invalid_idempotency_key, invalid_date_range | A malformed Idempotency-Key header, or a bad from/to on /usage. | No, fix the request. |
| 400 | unsupported_parameter | A parameter ewpire does not honor, such as stop, seed or n above 1. | No, remove it. |
| 400 | context_length_exceeded | The prompt is longer than the model's context. | No, shorten it or pick a model with a longer context. |
| 400 | unsupported_content | Images sent to a model that does not read images. | No. |
| 400 | content_filter | The request was declined by the model's safety filter. | No. |
| 401 | invalid_api_key | The key is missing, wrong or revoked. | No. |
| 404 | model_not_found | No model with that id is served through the API. | No. |
| 409 | idempotency_key_in_use | A request with the same Idempotency-Key is still running. | Yes, later. |
| 413 | request_too_large | The body is over 8 MB. | No. |
| 422 | idempotency_key_reused | The Idempotency-Key was used with a different body. | No, use a new key. |
| 429 | rate_limit_exceeded | Too many requests per minute for this key. | Yes, after Retry-After seconds. |
| 429 | insufficient_quota | Not enough credits for this request. | No, add credits first. |
| 429 | spend_limit_exceeded | The key's daily or monthly spend limit, or your monthly limit in a team, is reached. | No, until the limit resets or is raised. |
| 500, 502 | server_error | Something failed on our side or upstream. | Yes, with backoff. |
| 503 | model_unavailable, model_overloaded | The model is down or busy right now. | Yes, or use "auto". |
| 504 | timeout | The model took too long. | Yes. |
Retrying
The OpenAI SDKs retry 429 and 5xx answers by themselves. Two 429 answers cannot be fixed by waiting – insufficient_quota and spend_limit_exceeded – so they carry the header x-should-retry: false, which tells the SDKs not to retry.
To retry your own requests safely, send an Idempotency-Key header: a repeat of a request that already finished returns the same answer and is not charged twice. See Chat.
A failed request is not charged.