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.

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.
401	invalid_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.
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.
409	duplicate_request	A reservation already exists under this request id.	Yes, immediately.
429	rpm_exceeded / tpm_exceeded	This key’s per-minute ceiling.	Yes, after Retry-After. Back off.
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	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.
503	admission_unavailable	We could not verify credit for the request.	Yes, with backoff.

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-09-28.

Errors

Statuses

What is never charged

Retrying safely