API reference
Errors
Every error the API returns, in the OpenAI error envelope, and which ones are worth retrying.
Errors use the OpenAI error envelope, so OpenAI SDKs raise them as their usual error types. message is
meant for people; branch on the HTTP status and code.
{
"error": {
"message": "Unsupported text generation parameter: messages.0.tool_calls",
"type": "invalid_request_error",
"param": "messages.0.tool_calls",
"code": null
}
}Error codes
| Status | type | code | Meaning |
|---|---|---|---|
400 | invalid_request_error | invalid_json | The request body is not valid JSON. |
400 | invalid_request_error | null | The request failed validation, or the Authorization header is malformed. message explains the problem and param names the field. |
400 | invalid_request_error | model_not_found | The model ID is not in the catalog. |
401 | authentication_error | invalid_api_key | The token is missing, revoked, regenerated, mistyped, or an expired OAuth access token. |
403 | permission_error | no_active_plan | The account has no active plan and no top-up credits. |
403 | permission_error | insufficient_balance | Your balance cannot cover the estimated cost of the request. |
403 | invalid_request_error | content_policy_violation | Your input was flagged by content moderation. |
404 | invalid_request_error | null | The endpoint does not exist. |
413 | invalid_request_error | request_too_large | The request body is larger than 16 MB. |
429 | rate_limit_error | rate_limit_exceeded | The model is temporarily rate limited. |
500 | server_error | null | An unexpected error. |
503 | server_error | service_unavailable | Generation, or the token check, is temporarily unavailable. |
When the model itself rejects a request, for example a prompt longer than its context window, you get its status and message in the same envelope.
Validation errors
A 400 with a null code is a request the API refused to send to the model. param points at the problem:
- An unsupported field inside a message,
stream_optionsorreasoningis named in full, such asmessages.0.tool_calls, andmessagereadsUnsupported text generation parameter: …. - Any other problem with
modelormessages, such as atoolrole or an image incontent, setsparamtomodelormessages. - Other parameters are named by their path, such as
stoporreasoning.effort.
Unknown top-level parameters never cause this error: they are dropped. See Unsupported features.
Errors during a stream
Once a stream has started, the status is already 200. If generation then fails, the stream ends with an
error event instead of data: [DONE]:
data: {"error":{"message":"Upstream stream failed","type":"server_error","param":null,"code":"upstream_stream_error"}}Retrying
- Retry
429,500,503andupstream_stream_errorwith exponential backoff. - Don't retry other
4xxerrors unchanged: fix the request, the key, or the balance first. Afterinsufficient_balance, a lowermax_completion_tokensmay get the request through. - Failed requests are never billed, including streams that fail partway through, so retrying them costs nothing extra.