Skip to main content

​
Envelope

All errors follow OpenAI’s format: 
{
  "error": {
    "message": "Human-readable description",
    "type": "invalid_request_error",
    "code": "file_too_large",
    "param": "file"
  }
}
The body is always valid JSON. param is included when the error relates to a specific field.

​
Types

typeHTTPMeaning
invalid_request_error400 / 413Bad input, quota exceeded, unsupported format
invalid_request_error with code: model_not_found404Model slug doesn’t exist or isn’t available on your plan
auth_error401Missing or invalid API key
rate_limit_error429Per-key or per-IP rate limit hit
quota_exceeded402Out of credits or monthly budget reached
server_error5xxUpstream provider failure (often retried by fallback chain)

​
Common codes

codeMeaningFix
missing_api_keyNo Authorization headerAdd Bearer token
invalid_api_keyUnknown or revoked keyCreate a new key
expired_api_keyKey has passed its expiryRotate
model_not_foundSlug doesn’t existGET /v1/models to list available
model_not_supportedPlan doesn’t include this modelUpgrade or pick another
file_too_largeExceeds plan or provider limitUpload smaller
file_count_quota_exceededToo many stored files on planDelete old ones or upgrade
storage_quota_exceededStorage bytes capSame
unsupported_file_typeMIME not allowedCheck supported list
mime_mismatchFile content doesn’t match declared MIMEUsually an upload bug in client
file_not_foundfile_id doesn’t exist in workspaceCheck id, ensure same workspace
captcha_required / captcha_failedContact form protectionComplete Turnstile challenge
rate_limit_exceeded429Back off, retry with jitter
insufficient_creditsBalance too lowTop up or wait for monthly renewal
audio_not_supported_by_modele.g. Claude + audioTranscribe first

​
Error IDs

Every error response includes x-request-id. Include it when reporting issues — our support can look up the full request/response in seconds.

​
Retrying

Retryable (with exponential backoff + jitter):
  • 429 rate_limit_exceeded
  • 502, 503, 504
Not retryable:
  • 4xx other than 429 — they’re your client’s fault; fix the request
  • 402 insufficient_credits — top up first
Our fallback chains already retry server-side for you if configured — see Fallbacks.