Errors
Every error uses OpenAI’s envelope, so SDKs raise their usual exception types (the Anthropic paths use Anthropic’s, see Anthropic paths):
For the exact shape of every request and response, with curl, Python and Node examples, see the API reference.
{ "error": { "message": "'temperature' must be between 0 and 2.", "type": "invalid_request_error", "param": "temperature", "code": "invalid_value" }}type is one of invalid_request_error, permission_error, billing_error, rate_limit_error or server_error. param names the offending field when there is one. The x-request-id header is set on every response; quote it when you write to support.
400: bad request
Section titled “400: bad request”| code | Meaning |
|---|---|
invalid_json |
the body is not valid JSON or could not be read |
no_model_allowed |
an auto request whose model access leaves auto no model it can use. The message says which level to check: account, organization, project or key. See Model access |
missing_messages |
messages absent or empty (a missing model means auto) |
too_many_messages, too_many_tools |
more than 4096 messages or 256 tools |
invalid_value |
a field is out of range or malformed; param says which (on chat completions, modalities with audio and without text; on /v1/audio/speech, an input above 4,096 characters or a speed outside 0.25 to 4; on /v1/images/generations, n above 4, a size that is not WIDTHxHEIGHT, or a size or quality the named model does not produce, a response_format other than b64_json or url, or url with stream) |
unsupported_parameter |
a field Zabio does not implement (style on /v1/images/generations; n above 1, logprobs, prediction, the legacy function role, modalities or audio on the Responses API, which answers in text, a content part other than text, image_url and input_audio); tools sent to a model that cannot take them through Zabio (one whose capabilities.tools is false in GET /v1/models, or gpt-6-astra with stop, a max_tokens under 16, your own OpenAI key or in a batch; see Tools on gpt-6-astra) |
invalid_image_url |
an image could not be fetched or is not allowed; see Chat completions |
invalid_video_url |
a video URL could not be fetched, is not allowed, serves no MP4, MOV or WebM, or is over 20 MB on a model that does not fetch the video itself (send a bigger video as a file_id, or its URL to a Qwen model by name); see Chat completions |
unsupported_format |
the file sent to /v1/audio/transcriptions is not an audio format the endpoint accepts; see Audio |
missing_file |
/v1/audio/transcriptions without a file part |
unsupported_value |
a value no model can serve: on /v1/audio/transcriptions a response_format the model returns no timestamps for (srt, vtt, verbose_json), a language it does not serve, or diarized_json; on /v1/audio/speech a response_format the model does not produce, a voice it does not have, or an input longer than it takes; on chat completions and the Responses API an input_audio.format other than wav or mp3; on chat completions a modalities entry other than text and audio, an audio.format other than wav, mp3, flac, opus, pcm16 and aac, a custom voice object, or an audio.format or audio.voice the named model does not offer, or an audio.format it does not stream with stream: true (pcm16 only on the OpenAI models), see Chat completions; a video that is not MP4, MOV or WebM, or a video the named model’s vendor does not take (a YouTube URL or a WebM outside the Gemini models, a video sent as data over 10 MB of base64 to a Qwen model); on /v1/images/generations an output_format, a transparent background or a stream no model produces for the request, or response_format url on a server where image URLs are not enabled; param says which |
moderation_blocked |
the vendor’s safety system refused an image prompt or withheld a generated image; the message carries the vendor’s categories where it names any and the stage (input or output), never its text; see Images |
byok_key_invalid |
your organization’s own vendor key was rejected by the vendor; update it under Billing, vendor keys. Zabio never falls back to its own key |
upstream_invalid_request |
the vendor rejected the request; the message carries the vendor’s reason |
unsupported_for_model |
the model you named cannot do what the request asks; param names the field (Jev, jev-1.14.0 or jev-1.13.0, answers typed questions from a json_schema only, never text, tools, images or a stream; a transcription, speech or image model named on a chat endpoint, or a chat model named on an audio or images endpoint; an input_audio part sent to a model without audio_input, see Chat completions; an image part sent to a model without vision; a video part sent to a model without video_input, see Chat completions; the audio modality sent to a model without audio_output or to auto, or an assistant audio.id sent to auto or to a model of another vendor, see Chat completions) |
context_length_exceeded |
the request does not fit the context window of the model you named, or of any model auto can use for it. The message gives the request’s size in tokens (estimated at four characters a token), the max_tokens counted, and the window (under auto, the largest it can use); param is messages, or input on the Responses API. Shorten the input, lower max_tokens, or name a model with a larger window: GET /v1/models gives each model’s zabio.capabilities.context_window. The same request sent again gets the same answer. With no max_tokens on a model you named only the input counts, and a request close to the window is sent to the model; if the model refuses it the answer is upstream_invalid_request. On auto with no max_tokens, a model counts only when its window, less the 5 percent Zabio keeps free, leaves at least 4,096 tokens for the answer beside the input (or the model’s whole maximum output, when that is smaller), and the message says so when no model does. Anthropic models take a request whose input fits and are sent up to the model’s maximum output, or the max_tokens you set; an answer that reaches the window ends with finish_reason length. DeepSeek and Together AI models refuse a request whose input plus output limit passes the window, so close to the window Zabio sends them the room the window leaves beside the input, and the answer can be shorter than the model’s maximum; when less than 4,096 tokens of room remain, the model’s maximum output counts and the request is too long for that model. On every model but Anthropic’s, a max_tokens too large for the window is lowered to the room the window leaves, never below 4,096 tokens (or your own value, when that is smaller); with less room than that it counts as you set it. A request too long for the model you named is not moved to another model, except on Anthropic, DeepSeek and Together AI models, where a model of the same provider with a larger window serves it when the key’s fallback rules allow one; the 400 comes when none holds it. On the Responses API a stored conversation that no longer fits gets this code too; see Responses API |
conversation_mismatch, conversation_too_large |
Responses API; see Responses API |
401: authentication
Section titled “401: authentication”code: invalid_api_key when the key is missing, incorrect or revoked; the message says which. Keys are sent as Authorization: Bearer zb_live_....
code: key_expired when the key’s expiration has passed: "This API key expired on 2026-11-01 00:00 UTC. Create a new key or change its expiration in the web app." A key’s expiration is set when it is created or later in its Edit panel; its creator gets an email 7 days before. Background responses and batches the key queued before it expired end with the same code.
402: no credits
Section titled “402: no credits”{"error": {"message": "Your organization has no credits left. Add credits at zabio.ai/billing to continue.", "type": "billing_error", "code": "insufficient_credits"}}Returned before any vendor work, only when a zero balance means no service: the organization is set to stop at zero, or it is a person’s second organization, which has no Free allowance. Every other organization at zero runs on the Free limits instead (see Billing, “The Free plan”) and gets the free_tier_* codes below. The header x-zabio-balance-micros carries the balance. A named model served on your own vendor key is not refused; auto is, whatever keys you hold, because the classifier runs on Zabio’s key. A batch or a background response whose estimated cost exceeds the available balance is refused with this code too. So is a chat or Responses request, an image generation or edit, a speech call, a transcription or an embeddings call whose estimated cost does not fit the balance left after the calls still in flight: the message names the estimate, the balance and the least amount to add (see Billing, “What happens at zero”).
403: not allowed
Section titled “403: not allowed”| code | Meaning |
|---|---|
insufficient_scope |
the key lacks the scope for this endpoint (chat, embeddings or conversations) |
web_search_disabled |
the request asks for web search and the key has web search turned off (the key’s web_search setting). See Web search |
organization_suspended |
the organization is suspended |
conversations_closed |
stored conversations are closed for this organization |
free_tier_model |
the request names a model that is not on the free model list while the organization runs on the Free limits. The message is “Top up your account to unlock this model” with the top-up link; auto keeps working and picks among the free models. GET /v1/models marks locked models with zabio.availability: locked |
free_tier_limit with param members or api_keys |
the Free plan’s account caps, on the dashboard API: one member and two API keys until the first top-up |
prompt_injection_blocked |
the key’s prompt-injection guard action is block (or the request asked for it) and the guard found an injection pattern in the request. Nothing reached a model and nothing was billed. zabio.guard beside the error names where; see AI Firewall |
ip_not_allowed |
the call came from an address that the IP allow and deny lists of the organization, of the key’s project or of the key refuse. The message names the address the call came from and where the lists are set: "The address 198.51.100.7 is not allowed for this API key. An owner or admin of the organization sets the address lists in the dashboard, under AI Firewall, Network Access." When the address could not be read, it says so instead. It never says which list refused. Nothing reached a model and nothing was billed. Retrying from the same address gets the same answer; see IP allow and deny lists |
404: not found
Section titled “404: not found”model_not_found: the model does not exist, or Zabio does not offer it at the moment (the message names another model to use when there is one), or a level of the key’s model access (the account, the organization, the project or the key) does not allow it; an auto model (auto or one of its lines) that a level unchecked is refused the same way. The Responses API adds previous_response_not_found, conversation_not_found and response_not_found.
410: gone
Section titled “410: gone”model_retired: the request names a model past its retirement date (see Models); the message says the date and, when the vendor named a model that replaces it, that model, so you know which one to name instead. Zabio refuses it before any vendor work, so nothing is billed, on every endpoint that takes a model: chat completions, Responses, embeddings, speech, transcriptions, image generations and edits, videos, and the lines of a batch.
413: too large
Section titled “413: too large”payload_too_large: the body exceeds 32 MB. media_too_large: the audio file sent to /v1/audio/transcriptions exceeds 25 MB, or the input_audio parts of a chat completions or Responses request exceed what the model takes (100 MB decoded on Gemini models, 20 MB on the others), or its videos exceed 100 MB in all, or a video sent by URL to a Qwen model exceeds 2 GB; compress it or split it. A video part or an audio answer in a batch line answers unsupported_value for the line, and background: true with a video part answers 400 unsupported_parameter: Zabio does not keep videos until later.
Image edits and background generation
Section titled “Image edits and background generation”POST /v1/images/edits (see Images): 400 missing_file without an image[] file, missing_field without an images list in JSON; 400 invalid_multipart or invalid_json when the body is neither multipart nor JSON; 400 invalid_value for an image that is not png, jpeg or webp, a mask that is not png, more than 16 images, or more images than the named model takes, and in JSON for an image_url that is not a base64 data URL, a file_id the key cannot read or that is neither a user_data file nor an image, an image link that was changed, whose image was deleted, or that the key cannot read, a background generation that has not completed, or a zabio.index outside its images; 400 expired in JSON for a file_id whose file or generation has expired, or whose images were links that ran out after 60 minutes, or an image link in image_url that ran out; 400 unsupported_value for a mask on a model that takes none, zabio.background, or an image_url that is a web address other than an image link Zabio made (Zabio does not fetch it); 400 unsupported_parameter for input_fidelity or markup, or anything but index in an image’s zabio object; 413 media_too_large for an image above 50 MB, a body above 100 MB, input images above 100 MB in all, or input images above a named Google model’s limit of about 14 MB.
Background generations (see Images): 400 unsupported_value on zabio.background on the free plan; 400 invalid_value on zabio.expires_after without zabio.background, with another anchor than created_at or under 3600 seconds, and on the list for a limit, after or status outside its values; 402 insufficient_credits when the request is queued without credit, and as the error of a generation whose balance reached zero before it ran (nothing billed); on trial credit, also when the request’s estimated cost is above what is left of the trial, when it is queued or when it runs; 409 generation_in_progress on DELETE while the generation runs at the vendor; 410 expired on GET of a completed generation whose images were deleted or expired under the organization’s retention; 503 background_unavailable when the server cannot run background generations. A generation that fails carries status: failed and an error with the code and the message of a direct call’s failure.
Videos (see Videos): 400 invalid_value for seconds, size or resolution out of range or that a named model does not make, n above 1, no prompt and no input_reference, a zabio.last_frame without input_reference, or an image that is not png, jpeg or webp; 400 unsupported_value when no model can make the video asked, when the named model does not start from an image (or needs one), takes no last frame or always makes sound, for an image given as a web address, and for a variant other than video; 402 insufficient_credits when the credit does not cover the video’s estimate; 404 video_not_ready on /content before the video is completed; 409 video_in_progress on DELETE while the video is made; 410 expired on /content of a deleted or expired video; 503 video_unavailable when the server cannot make videos. A video that fails carries status: failed and an error: moderation_blocked (billed what the vendor charged, where it charges for a refusal, and the message says how much), generation_interrupted (the server restarted at the wrong moment; the message says whether a charge was returned), generation_timeout (not ready after six hours; nothing billed), insufficient_credits (the balance reached zero before it started; nothing billed), storage_unavailable, internal_error (an error on Zabio’s side; when the video was already billed the charge is returned and the message says so), or a vendor failure code above. A video link (zabio.url) answers 404 not_found once it expired, was changed, or its video was deleted.
The AI Firewall check (see AI Firewall check): 400 invalid_value names the item or field past a limit; on /v1/moderations, 400 unsupported_input names an image nothing would read (an https address, a format other than a PNG or JPEG data URL, any image without the model check).
429: slow down
Section titled “429: slow down”Every 429 carries a Retry-After header with the number of seconds to wait. Four limits exist:
| code | Scope | Details |
|---|---|---|
rate_limit_exceeded |
API key | the key’s requests per minute or tokens per minute bucket is empty. Defaults: 600 requests and 200,000 tokens per minute; set per key. The token bucket is charged up front with the input estimate plus the output budget, clamped to what the served model can produce, and settled after the call to the real usage; a max_tokens far above what the job needs can hit the limit early, so set it near what you need. Headers x-ratelimit-limit-*, x-ratelimit-remaining-* and x-ratelimit-reset-* for requests and tokens are set on every response |
quota_exceeded |
key or member (organization level) | the key’s spend limit is reached for its period (a day, a week from Monday or a month, from 00:00 UTC, or the key’s whole life), or the monthly quota of the member who created the key is reached. The message says when it resets, for example "This API key's spend limit of 5.00 USD has been reached. It resets on 2026-10-19 at 00:00 UTC.". Headers x-zabio-quota-scope (key or member), x-zabio-quota-limit and x-zabio-quota-remaining are set |
ip_rate_limit_exceeded |
client address | too many requests from one address, checked before authentication. Default 300 per minute. Headers x-ratelimit-*-ip are set only on the refusal |
upstream_rate_limited |
vendor | the vendor is rate limiting and every fallback was exhausted |
free_tier_limit |
organization, on the Free limits | one of the Free limits is met; param and the header x-zabio-free-limit name it: requests_per_day (100 successful requests a UTC day; Retry-After is the time to 00:00 UTC), requests_per_minute (20), daily_cost (the daily fair-use limit; it resets at 00:00 UTC), input_tokens (the request has more than 16,000 input tokens; no Retry-After, send a shorter request) or max_tokens (an explicit max_tokens above 2,000; lower it or leave it unset). The message says which limit, when it resets, and that a top-up removes every limit. The Free rate-limit headers (x-ratelimit-*-requests-day and the minute bucket in x-ratelimit-*-requests) are on every Free response, refusals included. See Billing |
rate_limit_exceeded, quota_exceeded and free_tier_limit use type: rate_limit_error.
5xx: server side
Section titled “5xx: server side”| Status | code | Meaning |
|---|---|---|
| 500 | internal_error |
an unexpected condition; the cause is never in the body |
| 500 | guard_unavailable |
under the guard’s redact action, the request could not be rewritten; nothing reached a model, retry the request |
| 502 | upstream_error |
the vendor returned an error or an unreadable response after retries and fallbacks. Retry-After: 5 when a retry makes sense |
| 503 | no_provider_available |
no healthy provider for this request right now; Retry-After: 5. A request too long for every model it may use gets 400 context_length_exceeded instead |
| 503 | vendor_unavailable |
the call named a model on a provider that is not available through Zabio right now; call another model or auto, or retry later; Retry-After: 5 |
| 503 | auth_unavailable, billing_unavailable, conversations_unavailable |
a Zabio dependency is temporarily unavailable |
| 503 | guard_unavailable |
POST /v1/guard/check or /v1/moderations could not run now: the patterns are switched off on Zabio’s side and the model check did not run; try again later, or ask for the model check |
| 503 | web_search_unavailable |
web search is switched off on Zabio’s side right now; send the request without it, or try again later |
| 503 | free_tier_unavailable |
the counters behind the Free limits could not be read, so a free call is refused rather than served unmetered; retry shortly. Paid calls are not affected. Also the answer of GET /v1/public/free-tier when the list cannot be read |
| 504 | upstream_timeout |
the vendor did not answer in time, or stopped sending data; Retry-After: 5 |
| 504 | request_timeout |
the request reached Zabio’s time limit before any answer: 20 minutes for a call that is not streamed, 10 minutes until the first piece of a streamed answer. When an attempt to a model provider failed before the limit, you get that attempt’s error instead. A stream that has started sending its answer is never cut by this limit. A call that runs this long has its 200 committed already (see below), so the error usually comes in the body or the stream, not as a 504 status |
Anthropic paths
Section titled “Anthropic paths”POST /v1/messages, POST /v1/messages/count_tokens and GET /v1/models sent with an anthropic-version header answer errors in Anthropic’s envelope, so the Anthropic SDKs raise their own exceptions (see Anthropic SDK and Claude Code). The message is the one in the tables above, and zabio.code is the code:
{"type": "error", "error": {"type": "rate_limit_error", "message": "Request rate limit reached for this API key. Retry after 2 seconds."}, "request_id": "req_6f1c...", "zabio": {"code": "rate_limit_exceeded"}}| Zabio’s status | Status on these paths | error.type |
|---|---|---|
| 400 | 400 | invalid_request_error |
| 401 | 401 | authentication_error |
| 402 | 402 | billing_error |
| 403 | 403 | permission_error |
| 404, 410 | 404 | not_found_error |
| 413 | 413 | request_too_large |
| 429 | 429 | rate_limit_error |
| 500, 502 | 500 | api_error |
| 503 | 529 | overloaded_error |
| 504 | 504 | timeout_error |
After a committed 200 (see below), a message that is not streamed carries this object as its whole body, and a stream ends with Anthropic’s error event, event: error with the same object. A vendor’s own error event is never passed on.
Errors after a committed 200 (long calls)
Section titled “Errors after a committed 200 (long calls)”To keep long calls alive, Zabio sends the 200 status as soon as a model provider accepts the request, or after 90 seconds at the latest (see “Long calls” in the chat completions and Responses guides). A failure after that point travels in the body, with status 200, so a 200 can carry an error: check for an error object before you read the answer.
| Call | Shape |
|---|---|
| chat completions, not streamed | only an error object, {"error": {"message", "type", "code", "request_id"}}, with no choices |
| chat completions, streamed | data: {"error": {"message", "type", "code", "request_id"}}, then a last chunk with finish_reason: "error", then data: [DONE] |
| Responses, not streamed | the response object with status: "failed" and error: {"code", "message"} |
| Responses, streamed | a response.failed event carrying that object |
The code values are the same as in the tables above. The OpenAI SDKs return a non-streamed 200 with an error body without raising, and raise on the error event of a stream.
Vendor errors and fallback
Section titled “Vendor errors and fallback”When a provider fails, Zabio retries on the next eligible model according to the routing rules (up to 3 attempts; explicit models follow zabio.fallback). Only when every option is exhausted do you see a vendor error. The vendor’s body never reaches you; x-zabio-vendor names the vendor that failed and the message carries the vendor’s reason for 400s. Content the vendor refuses to produce comes back as a normal response with finish_reason: "content_filter", not as an error.
During streaming, a failure after the stream has started is reported as an error object inside a chunk followed by a last chunk with finish_reason: "error" (chat completions) an error event (Responses API), or a {"type":"error"} event in place of speech.audio.done (speech with stream_format: sse), and the stream ends.
Two more codes on the Responses API
Section titled “Two more codes on the Responses API”missing_field(400): a required field such asinput, or an itemrole,contentorcall_idis missing. A missingmodelmeansauto.previous_response_not_foundandconversation_not_found(404) onPOST /v1/responses;response_not_found(404) applies toGETandDELETE /v1/responses/{id}.
Image links
Section titled “Image links”An image returned with response_format: url is a link to GET /v1/images/content/{file_id} that needs no API key. Once it has expired (60 minutes after the image was made), if any part of it was changed, or once its image was deleted, it answers 404 not_found, exactly as a path that does not exist, so a link never tells whether an image exists. A link cannot be renewed: download the image within the hour.
The full list per endpoint is in the API reference.