API error reference: the response format and every code
Every error the gateway itself returns has a JSON body with error.message, error.type and, most of the time, error.code. Write your application against code, not the message text. A failed request is not billed. Every response carries an X-Request-Id header, which is what you give support.
Last updated:
The error format
{
"error": {
"message": "Insufficient balance. Please top up your account.",
"type": "api_error",
"code": "insufficient_balance"
}
}codeis the machine code and stays stable, and every error in the tables below has one. Every401of the gateway carries one, and the413of a body over the size limit carriesrequest_too_large.- Some errors of the account API also carry
param: the name of the parameter that could not be read. typeisapi_errorfor gateway errors, except the rate limit, where it israte_limit_exceeded.messageis Persian; with the headerAccept-Language: enit is English. A few messages exist in Persian only, so never match on the message text.- The same format is used on
/anthropicand/geminifor the gateway's own errors.
The request id
Every response on /v1, /anthropic and /gemini, served or failed, has an X-Request-Id header (it starts with gw_). The same id is the request_id of that call's usage row and the reference of its wallet transaction. Send it when you write to support (response metadata).
X-Request-Id: gw_01JD3Z5T8Q0V6W4M2K9R7N1PXA
Every error code
| Status | Code | When it is returned | What to do |
|---|---|---|---|
400 | Code:invalid_request | When it is returned:The body cannot be parsed, a required field is missing (model, or max_tokens on the Anthropic route), or a field this route does not accept was sent (such as service_tier). On the account API: a from, to or request_id that cannot be read, or a CSV export range over the limit; there param names the parameter. | What to do:The message names the field. Correct the request (account API). |
400 | Code:hosted_tool_unmetered | When it is returned:A server-side tool that is not metered yet was requested (such as code_interpreter or file_search on Responses, or code_execution on Anthropic). | What to do:Remove that tool. The allowed tools are listed under function calling. |
400 | Code:search_not_priced | When it is returned:Web search was requested on a model that has no search rate. | What to do:Choose another model or remove the search tool. |
400 | Code:path_unmetered | When it is returned:background: true on /v1/responses, or stream: true on image generation. | What to do:Send the same request without that field. |
400 | Code:model_not_supported | When it is returned:The model requested for a realtime voice call is not one of the realtime models. | What to do:Choose one of the realtime models. |
400 | Code:offer_request_refused | When it is returned:A request to a special-offer model was not accepted. | What to do:Simplify the request, or call the regular model of the same family. |
400 | Code:batch_file_invalid | When it is returned:A batch input file (POST /v1/files) has a bad line: line is the number of the first bad line and reason its cause. | What to do:Fix that line and upload the whole file again (the input file's rules). |
401 | Code:missing_api_key | When it is returned:No key in Authorization, x-api-key or x-goog-api-key. | What to do:Send the key in a header (authentication). A key in the URL (?key=) is not read. |
401 | Code:invalid_api_key | When it is returned:A key 1xAi does not know. | What to do:Copy the key from the dashboard again, or create a new one. |
401 | Code:account_disabled | When it is returned:The key is known and its account is switched off. | What to do:Write to support. |
401 | Code:key_revoked | When it is returned:The key was revoked or has expired, or its workspace or company is not active. | What to do:Create a new key. |
401 | Code:key_capped | When it is returned:The key reached its own spend cap and was revoked. | What to do:Create a new key with a new cap (spend cap). |
401 | Code:workspace_limit | When it is returned:The monthly limit of the workspace or the member is used up. | What to do:Wait for the next month or raise the limit (teams and budgets). |
402 | Code:insufficient_balance | When it is returned:The account cannot fund the prompt plus one output token (or the fixed price of an image, audio or video call), or a message batch was submitted with a balance of zero or less. Or the wallet cannot fund an OpenAI batch's hold (with estimate_toman, required_toman and available_toman). | What to do:Top up. Calls work again as soon as a payment succeeds. |
402 | Code:plan_media_used | When it is returned:A media call (an image, a transcription, speech, a video or music) on an account whose paid chat plan has used up its media share for this period: media is now paid from the wallet, and the wallet cannot fund this call. Text calls are still paid from the plan's credit. | What to do:Top up the wallet. Media calls work again as soon as a payment succeeds. |
402 | Code:model_not_priced | When it is returned:The model has no row in our price list. An unpriced model is refused and never served for free. | What to do:Check the id against GET /v1/models. If the model is new, tell support. |
402 | Code:path_unmetered | When it is returned:A path whose cost cannot be metered yet (such as OpenAI Assistants and Uploads, Files with a purpose other than batch, or Gemini cachedContents). OpenAI Files and Batches work for batch processing (purpose=batch) only. | What to do:The full list is under unsupported endpoints; batch processing under OpenAI Batch. |
402 | Code:hosted_tool_unmetered | When it is returned:Google Maps grounding on Gemini, which is priced separately. | What to do:Use Google Search grounding instead. |
402 | Code:key_capped | When it is returned:An OpenAI batch's hold would pass the key's spend cap; the answer carries cap_toman, spent_toman and required_toman. The key is not revoked. | What to do:Raise the limit, or lower the output cap of the file's lines so the hold is smaller (the batch hold). |
402 | Code:workspace_limit | When it is returned:An OpenAI batch's hold has no room under the workspace's or the member's monthly limit. | What to do:Raise the limit, or lower the output cap of the file's lines so the hold is smaller (the batch hold). |
403 | Code:feature_disabled | When it is returned:A teen account whose parent switched off image, video or voice, or set quiet hours. | What to do:The parent's setting has to change. |
403 | Code:forbidden | When it is returned:A company workspace key asked for GET /v1/wallet/transactions or GET /v1/sla/credits; the ledger and the service credits belong to the whole company. | What to do:Read the spendable balance from GET /v1/wallet/summary; the ledger is on the company dashboard (account API). |
403 | Code:key_ip_not_allowed | When it is returned:The caller's address is not on the key's address list. | What to do:See the key's restrictions (key controls). |
403 | Code:key_scope_denied | When it is returned:The route is outside the key's scope. | What to do:See the key's restrictions (key controls). |
403 | Code:key_model_not_allowed | When it is returned:The model is not on the key's model list. | What to do:See the key's restrictions (key controls). |
404 | Code:path_not_found | When it is returned:The path does not exist or is not served through 1xAi; also any unknown path or method under /v1/usage, /v1/wallet and /v1/keys, the list of message batches (GET /anthropic/v1/messages/batches), and a vendor's own list of the objects it keeps (such as GET /v1/videos, or Gemini's list of operations, files, interactions and cachedContents), for every key. | What to do:Check the URL and the HTTP method against the documentation. |
404 | Code:not_found | When it is returned:The id you asked for (a key, a video or Midjourney task, a message batch, or an object a vendor keeps for a call: a Gemini operation, file or interaction, or a video) was not found or is not reachable with this key. An object another account or workspace created gets the same answer. So does an OpenAI batch or batch file, and a batch file you deleted. | What to do:Check the id and the key: an object is reachable with the keys of the account that made it, and in a company workspace with that workspace's keys (message batches). |
404 | Code:not_found | When it is returned:The request body names an object that is not reachable with this key: an OpenAI previous_response_id, conversation, prompt.id, item_reference or file_id, a Gemini fileUri (or file_uri), cachedContent or previous_interaction_id, or the file_id of an Anthropic file source. It is answered before anything is held, and nothing is billed. A batch file's file_id gets the same answer, even with its owner's key: those files serve batches only. | What to do:Remove that id from the body, or send the content in the request itself. Responses are not stored at OpenAI, so previous_response_id cannot be used (OpenAI-compatible endpoints). |
404 | Code:file_expired | When it is returned:A batch file's retention (1 day after the batch's settlement) is over, and it was deleted at OpenAI. | What to do:Download a batch's output within that time (retention and deletion). |
409 | Code:batch_not_settled | When it is returned:A batch's output or error file was deleted before the batch's cost was settled. | What to do:Delete it again a few minutes later; a batch is usually settled within a few minutes of its end. |
410 | Code:model_retired | When it is returned:The vendor retired this model. | What to do:Choose its replacement from the model list. |
413 | Code:request_too_large | When it is returned:The request body is larger than 25 MiB. A body over 26 MiB is refused before it reaches the gateway, with the same answer. | What to do:Send a smaller file, or in parts. base64 adds about a third to a file's size. |
413 | Code:batch_file_too_large | When it is returned:A batch input file is larger than 25 MB. | What to do:Split it into smaller files and make a batch of each (limits). |
415 | Code:unsupported_type | When it is returned:The route takes JSON and the Content-Type is something else. | What to do:Send Content-Type: application/json. |
429 | Code:rate_limit_exceeded | When it is returned:The key went over its own limit (1,000 requests a minute by default). | What to do:Wait for Retry-After (rate limits). |
429 | Code:upstream_capacity | When it is returned:The model's vendor is busy and refused the request; it is not your key's limit. On POST /v1/batches it means our batch queue at OpenAI is full. | What to do:Send again shortly, or choose another model. |
429 | Code:batch_limit | When it is returned:One of the account's batch limits: unsettled batches, their estimates together, requests a day, uploads at once, or the number and size of the files kept at OpenAI. The answer names the limit and the current figure. | What to do:Wait for a batch to be settled, or delete files you no longer need (limits). |
429 | Code:export_in_progress | When it is returned:Another CSV export of the same account (or workspace) is running. | What to do:Wait for Retry-After (CSV export). |
429 | Code:rate_limited | When it is returned:More than 6 CSV exports in a minute. | What to do:Wait for Retry-After. |
429 | Code:daily_limit | When it is returned:A teen account reached the daily spend limit its parent set. | What to do:It works again the next day. |
500 | Code:internal | When it is returned:A fault on our side. | What to do:Send again; if it repeats, give support the request id. |
502 | Code:upstream_error | When it is returned:The model's vendor could not be reached, or its answer could not be read. | What to do:Send again. Nothing was billed. |
503 | Code:upstream_unavailable | When it is returned:This model's vendor is not available through us right now. It has nothing to do with your key or balance. | What to do:Send again in a few minutes or choose another model; see the status page. |
503 | Code:usage_search_timeout | When it is returned:A q search of the usage report ran longer than 8 seconds. | What to do:Narrow the window with from and to, or find one call with request_id. |
503 | Code:offer_unavailable | When it is returned:A special-offer model has no capacity right now. The answer has a Retry-After header. | What to do:Send again after that time, or call the regular model. |
504 | Code:upstream_error | When it is returned:The vendor did not answer within 10 minutes. | What to do:When no answer arrived, nothing was billed. Make the request smaller, or send it with stream. |
Errors that come from the model vendor
- An error the vendor returns about the request itself (a wrong parameter, a prompt longer than the model's window, refused content) reaches you with the vendor's own status and body.
- On
/anthropicand/geminia vendor error has the vendor's own shape ({"type":"error",…}for Anthropic,{"error":{"status":…}}for Google). - When the problem is with our own account at the vendor, it is not presented as yours: you get
503with codeupstream_unavailable, never a401or402. - When the vendor does not know the model id, the answer carries a
suggested_modelfield with the closest available model.
What a failed request costs
A request that ends in an error is recorded in the usage report and is not billed. The one exception is an answer that was partly delivered and then cut: the delivered part is billed. Details are under billing.
1xAi is an independent gateway. It is not affiliated with, endorsed by, or a reseller for OpenAI, Anthropic, Google, DeepSeek, xAI, Moonshot AI, Z.ai, Alibaba Qwen, MiniMax or Tencent Hunyuan. Requests are relayed upstream rather than answered by models of our own, so each provider's own usage policies apply to what their models will and will not do, and their model availability is theirs to change. Current reachability is published on the status page.