Errors
The OpenAI error envelope, and a straight answer on which of these are worth retrying.
{
"error": {
"message": "Insufficient credit: this request needs up to $0.0042 but the balance is $0.0000.",
"type": "insufficient_quota",
"code": "insufficient_credit"
}
}Anthropic clients get the Anthropic envelope from /v1/messages instead. The code is stable and safe to branch on; the message is for a human and may be reworded.
Five routes, four envelopes. Each one is the shape the clients of that route already parse, so the error handling you have keeps working — what differs is the field names, never which request failed or why:
| Route | Envelope | Where the code is |
|---|---|---|
/v1/* | OpenAI | error.code |
/v1/messages | Anthropic | error.type |
/api/v3/images/generations | The Seedream API’s | error.code, in their vocabulary (InvalidParameter, AuthenticationError, SensitiveContentDetected) |
/v1beta/models/*:generateContent | google.rpc.Status | error.status (INVALID_ARGUMENT, UNAUTHENTICATED, RESOURCE_EXHAUSTED) with a numeric error.code |
/v1beta/openai/* | OpenAI | error.code — Google’s prefix, an OpenAI-shaped route, so the OpenAI envelope on every status |
The statuses below are the OpenAI envelope’s. Three of them differ per dialect, because each one answers in the status its own clients branch on:
| Condition | OpenAI | The Seedream API’s | google.rpc.Status |
|---|---|---|---|
| Out of credit | 402 insufficient_credit | 403 AccountOverdueError | 429 RESOURCE_EXHAUSTED |
| A content refusal | 400 moderation_blocked | 400 SensitiveContentDetected | 200 with finishReason: "IMAGE_SAFETY" |
| An unknown model | 404 model_not_found | 404 InvalidEndpointOrModel.NotFound | 404 NOT_FOUND |
None of the three is charged. The rest of the statuses below mean the same thing on every dialect; only the field names and the code vocabulary change.
Statuses
| Status | code | Cause | Retry? |
|---|---|---|---|
| 400 | invalid_body | The body is not JSON, or has no model field. | No — fix the request. |
| 400 | context_length_exceeded | The prompt is longer than the model accepts. | No — shorten it or use a longer-context model. |
| 400 / 413 | request_too_large | Too big to admit, before anything is sent: it could cost more than the ceiling on a single request, it could return more images than the endpoint can hand back, or — as 413, on the upload routes — an uploaded file is over the size limit. The message gives the bound it crossed. | No — lower n or max_tokens, ask for fewer or smaller images, or send a smaller file. |
| 400 | unsupported_parameter | A field this model or endpoint does not accept — reasoning on a model without reasoning control, max_tokens where the model wants max_completion_tokens. The message names the field, and so does error.param. | No — drop or rename the field. |
| 400 | unknown_parameter | A field we do not recognise at all, usually a typo. Named in the message and in error.param. | No — check the spelling against the endpoint’s reference. |
| 400 | invalid_request | The request could not be priced, so it was never admitted. | No — check n and max_tokens. |
| 401 | invalid_api_key / missing_api_key | Missing, malformed or revoked key. | No. |
| 403 | model_not_allowed | This key is restricted to other models. | No — widen the key or name a permitted model. |
| 403 | key_disabled | The key is real and is switched off. Distinct from 401 on purpose: nothing is wrong with the key you sent. | No — enable it or use another key. |
| 402 | insufficient_credit | The balance cannot cover the worst case for this request. | After topping up. The response carries X-Tokenify-Balance-Micro. |
| 404 | model_not_found | No such model, or it is disabled. | No — GET /v1/models lists what is available. |
| 410 | model_withdrawn | A model that was served here and no longer is. Distinct from 404 on purpose: the id was right, so this is not a typo to go looking for. | No — GET /v1/models lists what is available now. |
| 404 | image_expired / not_found | A generated image fetched after its retention window, or an id we have no record of. | No — generate it again. Download images you intend to keep. |
| 400 | unsupported_attachment | An image or a PDF sent to a model that reads text only. Refused here because forwarding it succeeds: the supplier drops the file, charges for the prompt and answers as though it had read it. | No — send it to a model whose architecture.input_modalities lists image. |
| 400 | wrong_endpoint | An image model sent to /v1/chat/completions, or a chat model to /v1/images/generations. | No — send it to the endpoint the message names. |
| 200 | queued (not an error) | A video job past the supplier’s concurrency limit is no longer refused: it is accepted and waits in one queue shared by every caller, in arrival order, and is submitted as a slot frees. The reply is the same shape as an immediate submit and carries the same job id; poll it and the status reads queued until it starts. This row stays in the table because a 429 video_capacity_exceeded used to be the answer here and client code written against it may still be looking for one. | No — nothing to retry. Poll the id you were given. |
| 503 | model_unavailable | A model this gateway does serve is temporarily out of service — taken out deliberately, usually during an incident. Distinct from model_not_available, which means the name was never ours. | Yes, shortly. Or use one of the models the message lists. |
| 400 or 404 | model_not_available | The model you named is OpenAI’s own and is not served here. The video endpoint answers 400 and the image endpoint 404, because one is a malformed request for a model that never existed here and the other is a lookup that found nothing. Their own APIs for several of these have been shut down; /docs/video/openai/ and /docs/images/openai/ have the dates. Only the model id needs to change. | No — change the model id first. |
| 400 | missing_required_parameter | A field the endpoint cannot proceed without was absent. The message and the param field name it. | No — add the field. |
| 502 | video_fetch_failed | The video exists and could not be fetched from storage. It has not been deleted and nothing is charged for the attempt — this is a fault of ours. Distinct from a 404, which means the object really is gone. | Yes. |
| 409 | video_not_ready | You asked for a video’s bytes before it finished. Nothing is charged for the attempt. Poll the job until its status is completed. | Yes, once the job reports completed. |
| 200 (polled) | generation_failed | Reported on the job rather than returned: the model could not produce the video. Nothing is charged for a job that produced nothing. | Yes. This is the model failing on one attempt, not a judgement about the request. |
| 503 | image_generation_failed | The supplier could not produce the image. Nothing is charged for a request that produced nothing — the reservation is released in full. | Yes. This is the supplier failing on one attempt, not a judgement about the request. |
| 500 | queued_job_vanished | Your request was queued and its record is no longer there. Nothing is charged: the hold is released with the record. This is a fault of ours, not of the request. | Yes, and it should succeed — report it if it recurs. |
| 500 | queued_job_without_images | A queued request finished without producing anything to serve. Nothing is charged. Like the row above this is our fault rather than the request’s. | Yes. |
| 200 (polled) | queue_wait_exceeded | The job waited for a supplier slot for as long as we are willing to hold your money against work that has not started, and no slot came. Nothing was generated and the reservation is released in full. | Yes — the queue was saturated for the whole window, so a later attempt is a different queue. |
| 200 (polled) | submit_outcome_unknown | We sent this job to the supplier and never learned whether they took it — the connection failed or the reply was unreadable. Nothing is charged and the reservation is released in full. We deliberately do not retry: a second attempt would risk paying for two generations of the same clip, so one uncertain job is absorbed instead. | Yes — submit it again if you still want the clip. |
| 200 (polled) | dispatch_attempts_exhausted | The supplier refused this job several times for a reason that looked temporary — capacity, or being unreachable — and we stopped asking. Nothing was generated and the reservation is released in full. Stated separately from a wait that ran out because the cause is different: somebody was asked and said no, rather than nobody getting to it. | Yes, though a different model or resolution is more likely to be accepted. |
| 429 | video_jobs_in_flight | Your key already has as many video jobs running as it is allowed. Unlike the limit above, this one is yours and can be raised. | Yes — poll the jobs you have and retry when one finishes. |
| 404 | video_expired | A generated video that is past its retention. Videos are kept for seven days, like images, and the link is on this domain rather than the supplier’s. | No — generate it again. |
| 409 | running_task_deletion | A delete sent for a video job that is still running. A job cannot be cancelled once it has been accepted: the supplier refuses the same thing, and the work is billed either way. | No — poll it to completion, then delete the record if you want it gone. |
| 400 | invalid_resolution | A resolution this video model does not generate. The message lists the ones it does — they differ between models of the same family. | Yes, with a resolution from the message. |
| 400 | invalid_duration | A clip shorter or longer than this video model generates. The message gives its range; one family stops at 15 seconds and another at 30. | Yes, with a duration inside the range. |
| 400 | unsupported_task | Reference or video input sent to a video model that takes only text and image input. The message says what the model accepts. | Yes, with input the model accepts, or on a model that accepts it. |
| 400 | missing_prompt | A video request with no text prompt. | Yes, with a prompt. |
| 400 | invalid_size | A size outside this image model’s pixel range or aspect range. The message gives the range and names the nearest size the model makes. | Yes, with the nearest size from the message. |
| 400 | invalid_image | An image you sent cannot be used: too few or too many pixels, a format whose dimensions we cannot verify, or not an image at all. error.param names which one of them it was. | No — re-encode it as PNG, JPEG or WebP, within the range the message gives. |
| 400 | moderation_blocked | The content policy refused the prompt, an image you sent, or the image it produced. | No. Nothing was charged. |
| 400 | upstream_rejected | The model refused the request itself. Usually the size, the prompt, or a reference image. | No — change the request. Nothing was charged. |
| 409 | duplicate_request | A reservation already exists under this request id. | Yes, immediately. |
| 429 | rpm_exceeded / tpm_exceeded / ipm_exceeded | This key’s per-minute ceiling. Images are counted in images, not tokens. | Yes, after Retry-After. Back off. |
| 429 | model_rpm_exceeded / model_tpm_exceeded / model_ipm_exceeded | The ceiling for this model across every key, not yours. One model being busy does not touch your limit on the others. | Yes, after Retry-After. Another model will usually serve immediately. |
| 429 | too_many_image_requests | Too many image requests are in flight on this deployment, across every key. An image reply is the largest thing this API sends, so a small number are served at once deliberately. | Yes, after Retry-After. Text requests are unaffected. |
| 429 | (from upstream) | The supplier rate-limited us. | Yes, with backoff. We try other suppliers first. |
| 502 | upstream_unavailable | Every supplier for this model failed before responding. | Yes. No credit was charged. |
| 502 | upstream_error | The supplier answered and could not produce the image. | Yes. Nothing was charged. |
| 502 | upstream_reply_too_large | The reply is larger than this endpoint buffers. For an image, that is the generated file; for a completion, it is the JSON — a high top_logprobs on a long answer is the usual cause. | Yes — for an image ask for jpeg or a smaller size; for a completion send stream: true, which needs no buffer. |
| 504 | reply_wait_timeout | The reply arrived but could not be buffered before this request deadline, because a small number of large replies are held at once deliberately. | Yes. Or send stream: true, which needs no buffer. |
| 502 | upstream_unmetered | The model returned an image without reporting what it used, on a model charged by use. Nothing was delivered. | Yes. Nothing was charged. |
| 502 | upstream_unreadable | The supplier answered with something we could not read. | Yes — and tell us the request id. |
| 502 | translation_failed | The supplier answered and we could not render it in your dialect. | Yes — and tell us the request id, because that one is ours. |
| 500 / 502 | internal_error / image_store_failed | Ours. We could not prepare the request, or could not store what came back. | Yes — and tell us the request id, because that one is ours. |
| 503 | admission_unavailable | We could not verify credit for the request. | Yes, with backoff. |
| 503 | auth_unavailable / balance_unavailable | We could not check the key, or could not read the balance, so the request was not admitted rather than served unpriced. | Yes, with backoff. |
| 503 | no_route / no_upstream | The model is served here but no supplier can take it at this moment. | Yes, with backoff, or name another model. |
| 503 | unavailable / model_misconfigured | The image store is unreachable, or a model is not configured completely enough to be billed — in which case we refuse it rather than serve it free. | Yes, with backoff. Tell us the request id if it persists. |
What is never charged
Credit is reserved before a request is sent and released if nothing is generated. You are not charged for a 4xx the supplier rejected, for a request that never reached a supplier, or for one where every supplier failed. You are charged for tokens a supplier generated before a stream broke, because they generated them.
Retrying safely
Retries are safe: a request is only ever billed once, and a retry after a lost response is a new request rather than a duplicate charge. Use exponential backoff with jitter on 429, 502 and 503, and do not retry a 4xx that describes the request itself — every supplier will make the same judgement.
x-tokenify-request-id. It is the only identifier that finds a request in our system, and quoting it lets support see exactly what happened to that one request.Last updated 2026-10-13.