Errors - NoMask

Errors use the OpenAI envelope, so SDK exception types work as expected. Every response, success or failure, carries an X-Request-Id header; include it when contacting support.

The error envelope

{
  "error": {
    "message": "You are sending requests too quickly. Slow down and retry after 21 seconds.",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "param": null
  }
}

type follows the OpenAI convention (invalid_request_error, authentication_error, permission_error, rate_limit_error, server_error). code is the precise machine-readable reason, and param names the offending request field when there is one.

Status codes

Status	Type	When
400	`invalid_request_error`	Malformed body, invalid or unsupported parameter, bad image, context too long, or a content policy violation.
401	`authentication_error`	Missing, incorrect, revoked, or expired API key.
402	`invalid_request_error`	Your API balance is empty.
403	`permission_error`	Your account does not have API access.
404	`invalid_request_error`	Unknown model or unknown endpoint.
413	`invalid_request_error`	Request payload too large.
429	`rate_limit_error`	Rate limit or a key’s monthly spending limit reached.
500	`server_error`	Internal error. Safe to retry.
502	`server_error`	The model failed to produce a response. Safe to retry.
503	`server_error`	Model busy or overloaded, or the API is in maintenance. Retry with backoff.
504	`server_error`	The model timed out. Safe to retry.

Error code reference

Code	Status	Meaning
`missing_parameter`	400	A required field (like `model` or `messages`) is absent.
`invalid_parameter`	400	A field has the wrong type or is out of range. `param` names it.
`unsupported_parameter`	400	A recognized OpenAI field this API does not support (e.g. `logprobs`).
`invalid_request`	400	The body is not a JSON object, or another structural problem.
`model_lacks_vision`	400	An image was sent to a non-vision model.
`model_lacks_video`	400	The selected model does not accept video. Choose a model marked Video input.
`invalid_video` / `video_unsupported_format` / `video_duration_exceeded` / `video_fetch_failed`	400	The clip could not be read or exceeds this model’s format or duration limits. See Video Inputs.
`video_too_large`	413	The actual video file exceeds this model’s maximum file size.
`model_lacks_function_calling`	400	`tools` was sent to a model without the function_calling capability.
`invalid_image`	400	Corrupted, too small, too large, or unsupported image.
`context_length_exceeded`	400	The conversation does not fit the model’s context window. Shorten it or pick a larger-context model.
`content_policy_violation`	400	The request was flagged by the content policy, or the model’s response was blocked by a content filter. Rephrase the prompt and retry; some models apply stricter filtering than others.
`missing_api_key` / `invalid_api_key` / `api_key_expired` / `api_key_revoked`	401	Authentication problems; see Authentication.
`insufficient_balance`	402	Your balance is empty. Fund it from the dashboard.
`account_restricted`	403	The account is not allowed to use the API.
`model_not_found`	404	Unknown or disabled model id.
`unknown_endpoint`	404	The path does not exist under /v1.
`payload_too_large`	413	The request body exceeds the size limit.
`rate_limit_exceeded`	429	A request allowance or the text token allowance was reached. Honor `Retry-After`.
`monthly_limit_exceeded`	429	The key hit its monthly USD cap.
`internal_error`	500	Unexpected server error.
`upstream_error` / `upstream_unavailable` / `invalid_upstream_response`	502	The model failed to generate. Retry.
`model_overloaded`	503	The model is at capacity right now.
`model_busy`	503	The model is temporarily busy. Retry later or switch models; this is not your account limit.
`service_unavailable`	503	The API is temporarily disabled for maintenance.
`video_input_unavailable`	503	Video processing is temporarily unavailable. Retry later.
`timeout`	504	The model took too long to respond.

Handling errors

Retry 5xx and 429 with exponential backoff; honor Retry-After when present.
Do not retry 400/401/402/403/404 unchanged; fix the request or account state first.
Use idempotency keys so network-level retries can never double-bill.
Log the X-Request-Id header with failures; it lets support trace the exact request.