Errors
All API error codes and what to do about them.
An error comes with an HTTP status and a body in the format of the endpoint. For /v1/chat/completions, /v1/responses, /v1/embeddings, images, video and speech:
{
"error": {
"type": "insufficient_quota_error",
"code": "insufficient_funds",
"message": "organization balance insufficient for this request"
}
}In the OpenAI format, rely on error.code: it is stable, and the message text can change.
For /v1/messages the body is in the Anthropic format: {"type": "error", "error": {"type": "...", "message": "..."}}. It has no error.code field, except for key_revoked. Tell errors apart by the HTTP status, error.type and the error.message text:
| Status | error.type | Codes from the tables below |
|---|---|---|
| 400, 404, 413 | invalid_request_error | request, model_not_found, request_too_large |
| 401 | authentication_error | invalid_api_key, key_revoked |
| 402 | insufficient_quota_error | insufficient_funds, key_limit_exceeded, spend_limit_exceeded |
| 403 | permission_error | model_not_allowed, pii_masking_not_enabled, account_blocked |
| 429 | rate_limit_error | rate_limit_exceeded |
| 500, 502, 503 | api_error | internal_error, provider_error, service_unavailable |
Errors before the money reserve (401, 403, 404, 400 and 413) cost nothing.
Every response has the X-Request-Id header. Give it to support if you need a request investigated.
Request
invalid_jsonThe request body could not be parsed. Check the JSON.model_category_mismatchThe model category does not fit the endpoint: an embeddings, speech or video model in /v1/chat/completions, a non-speech model in /v1/audio/transcriptions, an image model in /v1/messages, /v1/responses or /v1/embeddings, a text model in /v1/images/generations or /v1/embeddings. An image model in /v1/chat/completions is allowed. Choose a model of the right category from the list.stateful_not_supportedThe /v1/responses request has store: true or previous_response_id. Remove the fields and send the whole history in every request.invalid_pii_masking_headerIn X-PII-Masking the value is not one of on, off, true, false, 1, 0.pii_masking_unsupported_endpointX-PII-Masking: on on an endpoint without masking: embeddings, speech, images. Remove the header or set off.unsupported_response_formatAn image request asks for response_format: "url". Use b64_json.image_streaming_unsupportedAn image request has stream: true. Remove the field.invalid_image_countn in an image request is not an integer from 1 to 10.unsupported_video_parameterThe duration, resolution or aspect ratio is not in the video model's list, or a file is passed in input_reference. Check the allowed values on the model.invalid_secondsThe video duration could not be parsed. Pass a number of seconds.missing_promptThe video request has no prompt.missing_modelThe video request has no model.invalid_multipartThe multipart body of the speech request could not be parsed.request_too_largeThe body is larger than 32 MiB (26 MiB for speech). Reduce the request.Key and access
invalid_api_keyThe key is missing, invalid, revoked or expired. Check the header and the key status in the console.key_revokedThe key was revoked while the request was running. The request is cut off, and in a stream the error comes as the last event. Spending is counted by what was already received.model_not_allowedThe model is not in the key's list. Choose a model from GET /v1/models or extend the list in the console.pii_masking_not_enabledThe X-PII-Masking: on is sent, but the masking option is not enabled for the organization. Remove the header or enable the option.account_blockedThe organization is blocked or inactive. Contact support.model_not_foundThere is no such model in the catalog. Compare the name with GET /v1/models.Money and limits
insufficient_fundsThe balance does not cover the request reserve. Top up the balance or pass a smaller max_tokens.key_limit_exceededThe daily or monthly spending limit of the key is used up. The message names the period, and for a limit by type or model also kind or model. Wait for the period to start or raise the limit.spend_limit_exceededThe spending limit of the employee, team or organization is used up. The message names the scope and the period.rate_limit_exceededMore than 120 requests or 200,000 tokens per minute. Retry after the time in the Retry-After header.In the Anthropic format, the three reasons for a 402 differ in the error.message text:
organization balance insufficient for this request:insufficient_funds;spending limit of this API key for the <period> is exceeded:key_limit_exceeded(for a limit by type or model,for <type> generationorfor model <model>is appended);spending limit of the <scope> for the <period> is exceeded:spend_limit_exceeded.
Video
video_not_foundThere is no such job, or it belongs to another organization.video_not_readyThe file was requested before the job finished. Check the status with GET /v1/videos/{id}.video_cancel_unsupportedA job already passed to the provider cannot be cancelled. Wait for it to finish.If video generation ends with the failed status, no money is charged. The reason is in the error field of the job: for example timeout (the job did not finish within an hour), provider_error, cancelled, key_revoked.
Service and provider
provider_errorThe model provider rejected the request. Retry later.internal_errorInternal error. Retry the request and report X-Request-Id if it persists.The service returns a provider's own error (model unavailable, moderation, regional restrictions) as is, in the provider's format, with its status and body. Any such status with Retry-After can be retried after a pause.
It is safe to retry 429, 502 and 503: on a 503 no money was reserved. Before retrying a 402, top up the balance or the limit. Before retrying a 400 or 403, fix the request.