Documentation
Errors
Every status and code the API returns.
Error shape
Errors match OpenAI's shape. Branch on code — it is stable, while message is written for a human and may change.
1{2 "error": {3 "message": "Insufficient credits. Add credits to keep using the API.",4 "type": "insufficient_quota",5 "code": "insufficient_credits"6 }7}Status and codes
| Status | Code | Meaning |
|---|---|---|
| 400 | missing_model, missing_messages | A required field is absent or empty. |
| 400 | too_many_messages, too_many_tools, too_many_images, too_many_audio, too_many_video | Over one of the size limits. |
| 400 | image_too_large, audio_too_large, video_too_large | A single file is over 5 MB. |
| 400 | unsupported_image_url, unsupported_audio_url, unsupported_video_url | Media was sent as a link. Send base64 instead. |
| 400 | unsupported_image_type, unsupported_audio_format, unsupported_video_type | That container or codec is not one we pass through. |
| 400 | images_not_supported, audio_not_supported, video_not_supported | That model does not read that kind of input. |
| 400 | upstream_validation | The model rejected the request — usually the context window. |
| 401 | missing_api_key, invalid_api_key, key_disabled, key_expired | The key is absent, unknown, disabled or expired. |
| 402 | insufficient_credits, key_limit_reached, workspace_budget_reached, guardrail_limit_reached | A spending limit was reached. The message names which. |
| 403 | model_not_allowed, wrong_key_kind | A guardrail blocks that model, or a management key tried to call one. |
| 404 | model_not_found, preset_not_found | No such model or preset. |
| 413 | request_too_large | The body is over 8 MB. |
| 429 | rate_limit_exceeded | The key's per-minute allowance is spent. Wait Retry-After seconds. |
| 429 | upstream_rate_limited | The model is saturated. Back off and retry. |
| 499 | cancelled | You disconnected before the reply finished. |
| 500 | internal_error | Our fault. Safe to retry. |
| 502 | upstream_error | The model returned something we could not interpret. |
| 503 | model_unavailable, upstream_unavailable | We list the model but cannot serve it right now. |
| 504 | upstream_timeout | The model took too long. |
Retrying
Retry on 429, 500, 502, 503 and 504, with exponential backoff and a jitter. Everything in the 400s will fail the same way until you change the request.
A retry is a new, separately billed request
There are no idempotency keys yet, so a retry that succeeds after a timeout may mean you paid for both attempts. Prefer streaming for long generations, where a partial result is visible rather than lost.