Tokenify

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:

RouteEnvelopeWhere the code is
/v1/*OpenAIerror.code
/v1/messagesAnthropicerror.type
/api/v3/images/generationsThe Seedream API’serror.code, in their vocabulary (InvalidParameter, AuthenticationError, SensitiveContentDetected)
/v1beta/models/*:generateContentgoogle.rpc.Statuserror.status (INVALID_ARGUMENT, UNAUTHENTICATED, RESOURCE_EXHAUSTED) with a numeric error.code
/v1beta/openai/*OpenAIerror.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:

ConditionOpenAIThe Seedream API’sgoogle.rpc.Status
Out of credit402 insufficient_credit403 AccountOverdueError429 RESOURCE_EXHAUSTED
A content refusal400 moderation_blocked400 SensitiveContentDetected200 with finishReason: "IMAGE_SAFETY"
An unknown model404 model_not_found404 InvalidEndpointOrModel.NotFound404 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

StatuscodeCauseRetry?
400invalid_bodyThe body is not JSON, or has no model field.No — fix the request.
400context_length_exceededThe prompt is longer than the model accepts.No — shorten it or use a longer-context model.
400 / 413request_too_largeToo 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.
400unsupported_parameterA 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.
400unknown_parameterA 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.
400invalid_requestThe request could not be priced, so it was never admitted.No — check n and max_tokens.
401invalid_api_key / missing_api_keyMissing, malformed or revoked key.No.
403model_not_allowedThis key is restricted to other models.No — widen the key or name a permitted model.
403key_disabledThe 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.
402insufficient_creditThe balance cannot cover the worst case for this request.After topping up. The response carries X-Tokenify-Balance-Micro.
404model_not_foundNo such model, or it is disabled.No — GET /v1/models lists what is available.
410model_withdrawnA 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.
404image_expired / not_foundA 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.
400unsupported_attachmentAn 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.
400wrong_endpointAn image model sent to /v1/chat/completions, or a chat model to /v1/images/generations.No — send it to the endpoint the message names.
200queued (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.
503model_unavailableA 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 404model_not_availableThe 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.
400missing_required_parameterA field the endpoint cannot proceed without was absent. The message and the param field name it.No — add the field.
502video_fetch_failedThe 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.
409video_not_readyYou 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_failedReported 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.
503image_generation_failedThe 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.
500queued_job_vanishedYour 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.
500queued_job_without_imagesA 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_exceededThe 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_unknownWe 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_exhaustedThe 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.
429video_jobs_in_flightYour 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.
404video_expiredA 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.
409running_task_deletionA 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.
400invalid_resolutionA 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.
400invalid_durationA 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.
400unsupported_taskReference 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.
400missing_promptA video request with no text prompt.Yes, with a prompt.
400invalid_sizeA 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.
400invalid_imageAn 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.
400moderation_blockedThe content policy refused the prompt, an image you sent, or the image it produced.No. Nothing was charged.
400upstream_rejectedThe model refused the request itself. Usually the size, the prompt, or a reference image.No — change the request. Nothing was charged.
409duplicate_requestA reservation already exists under this request id.Yes, immediately.
429rpm_exceeded / tpm_exceeded / ipm_exceededThis key’s per-minute ceiling. Images are counted in images, not tokens.Yes, after Retry-After. Back off.
429model_rpm_exceeded / model_tpm_exceeded / model_ipm_exceededThe 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.
429too_many_image_requestsToo 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.
502upstream_unavailableEvery supplier for this model failed before responding.Yes. No credit was charged.
502upstream_errorThe supplier answered and could not produce the image.Yes. Nothing was charged.
502upstream_reply_too_largeThe 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.
504reply_wait_timeoutThe 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.
502upstream_unmeteredThe model returned an image without reporting what it used, on a model charged by use. Nothing was delivered.Yes. Nothing was charged.
502upstream_unreadableThe supplier answered with something we could not read.Yes — and tell us the request id.
502translation_failedThe supplier answered and we could not render it in your dialect.Yes — and tell us the request id, because that one is ours.
500 / 502internal_error / image_store_failedOurs. 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.
503admission_unavailableWe could not verify credit for the request.Yes, with backoff.
503auth_unavailable / balance_unavailableWe could not check the key, or could not read the balance, so the request was not admitted rather than served unpriced.Yes, with backoff.
503no_route / no_upstreamThe model is served here but no supplier can take it at this moment.Yes, with backoff, or name another model.
503unavailable / model_misconfiguredThe 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.

Always log 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.