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 statusCodeTypeDescription
400invalid_jsoninvalid_request_errorThe request body is not valid JSON.
400invalid_requestinvalid_request_errorThe request body is malformed or contains an invalid value.
400unsupported_parameterinvalid_request_errorThe parameter needs server-side state we never keep (for example previous_response_id or background on /v1/responses).
400unsupported_contentinvalid_request_errorThe model does not accept this content type (for example, image input).
400image_url_not_supportedinvalid_request_errorImage URLs are not fetched. Send the image inline as a base64 data URL (data:image/png|jpeg|webp|gif;base64,...).
400context_length_exceededinvalid_request_errorThe prompt and requested output do not fit in the model's context window.
400invalid_support_subjectinvalid_request_errorThe support request subject is empty or too long.
400invalid_support_bodyinvalid_request_errorThe support request message is empty or too long.
401invalid_api_keyauthentication_errorThe API key is missing, malformed or revoked.
401authentication_requiredauthentication_errorThe panel session is missing or expired.
403origin_not_allowedpermission_errorThe request came from an origin that is not allowed to call the panel API.
402insufficient_balanceinsufficient_balance_errorThe project balance cannot cover the request's reservation.
404model_not_foundnot_found_errorNo active model has this id.
413request_too_largeinvalid_request_errorThe request body exceeds the size limit.
429rate_limit_exceededrate_limit_errorThe project sent too many requests per minute.
429concurrency_limitrate_limit_errorThe project has too many requests in flight.
429model_capacityrate_limit_errorThe model is temporarily at capacity. Retry after the Retry-After interval.
429support_rate_limitedrate_limit_errorThe account opened too many support requests. Retry after the Retry-After interval.
500internal_errorapi_errorAn unexpected error occurred on our side.
502upstream_errorapi_errorThe model failed to produce a response.
503model_unavailableapi_errorThe model is temporarily unavailable.
504upstream_timeoutapi_errorThe model did not respond in time.

Causes and fixes#

CodeCause and solution
400 Invalid requestCause: 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 contentCause: 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 failedCause: 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 balanceCause: 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 ForbiddenCause: 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 foundCause: 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 largeCause: 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 requestsCause: 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 errorCause: 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 errorCause: the model failed while producing the response (upstream_error). Solution: retry. Nothing is billed if no content was returned.
503 Model unavailableCause: the model is temporarily offline (model_unavailable). Solution: retry later, or switch to another model.
504 TimeoutCause: 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.