Errors

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

`type`	HTTP	Meaning
`invalid_request_error`	400 / 413	Bad input, quota exceeded, unsupported format
`invalid_request_error` with `code: model_not_found`	404	Model slug doesn’t exist or isn’t available on your plan
`auth_error`	401	Missing or invalid API key
`rate_limit_error`	429	Per-key or per-IP rate limit hit
`quota_exceeded`	402	Out of credits or monthly budget reached
`server_error`	5xx	Upstream provider failure (often retried by fallback chain)

Common codes

`code`	Meaning	Fix
`missing_api_key`	No `Authorization` header	Add Bearer token
`invalid_api_key`	Unknown or revoked key	Create a new key
`expired_api_key`	Key has passed its expiry	Rotate
`model_not_found`	Slug doesn’t exist	`GET /v1/models` to list available
`model_not_supported`	Plan doesn’t include this model	Upgrade or pick another
`file_too_large`	Exceeds plan or provider limit	Upload smaller
`file_count_quota_exceeded`	Too many stored files on plan	Delete old ones or upgrade
`storage_quota_exceeded`	Storage bytes cap	Same
`unsupported_file_type`	MIME not allowed	Check supported list
`mime_mismatch`	File content doesn’t match declared MIME	Usually an upload bug in client
`file_not_found`	`file_id` doesn’t exist in workspace	Check id, ensure same workspace
`captcha_required` / `captcha_failed`	Contact form protection	Complete Turnstile challenge
`rate_limit_exceeded`	429	Back off, retry with jitter
`insufficient_credits`	Balance too low	Top up or wait for monthly renewal
`audio_not_supported_by_model`	e.g. Claude + audio	Transcribe 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.

Overview

Chat Completions

Embeddings

Images

Audio

Video

Music

Files

Models

Envelope

Types

Common codes

Error IDs

Retrying

​Envelope

​Types

​Common codes

​Error IDs

​Retrying

Envelope

Types

Common codes

Error IDs

Retrying