Errors
HTTP error codes, response formats, and retry rules.
No current prepared translation is available. The English source is shown without machine translation.
| HTTP | Meaning | Recommended action |
|---|---|---|
| 400 | Invalid request | Correct JSON and required fields |
| 401 | Invalid, frozen, or revoked key | Rotate or unfreeze the key |
| 402 | Insufficient account balance or key usage limit reached | Add funds or reset/increase the key limit |
| 403 | Model unavailable for the key or source IP rejected by an API allowlist | Update key permissions or use an allowed source IP |
| 404 | Unknown endpoint, model, or async request | Check the identifier and path |
| 413 | Request too large | Reduce context size |
| 429 | RPM or concurrency exceeded | Honor Retry-After |
| 500 | Gateway error | Inspect state and logs before considering another paid request |
| 502/503/504 | Upstream unavailable or timed out | Distinguish safe reads from a potentially accepted paid POST |
Payment required
Insufficient company/account balance returns HTTP 402 Payment Required in the OpenAI-compatible envelope:
{
"error": {
"message": "Insufficient account balance.",
"type": "payment_required",
"code": "insufficient_balance"
}
}The same stable reason/code is recorded in Request History. A 402 request is rejected before provider execution and should not be automatically retried until funding or the applicable spending constraint has been corrected.
IP allowlist rejection
When an authenticated API key is valid but the source address is outside the effective personal or Business organization API allowlist, Model Gate rejects the request before upstream execution. OpenAI-compatible responses use HTTP 403 with code ip_not_allowed. Anthropic-compatible responses use the Anthropic error envelope with HTTP 403 and authentication_error. Do not retry from the same disallowed source; change the configured allowlist or send the request from an allowed address.
Retry 429 after Retry-After. For safe read-only operations, bounded backoff may be appropriate after 500, 502, 503 or 504. Do not apply that rule blindly to paid inference POSTs. Do not automatically retry validation, authentication, balance, or not-found errors.
Use the request public ID from X-Request-ID to correlate the response with the request log.
Errors after stream headers
SSE can fail after HTTP200 has already been sent. The response then contains a protocol-compatible error event; your request history can record a failure independently of the initial HTTP status. Provider error details may be replaced with a safe message. Missing usage after an interrupted stream is unknown, not an estimate from response bytes. Preserve the request ID and check partial output before retrying; contact Support without sharing keys or sensitive content.
Dedicated Images failures
Images uses an image_request_error envelope for its own validation/control errors. Preserve the original Idempotency-Key, exact request and operation ID. A successful HTTP response can still carry a terminal operation status; inspect status and error_code. outcome_unknown or review_required means stop and seek operator review, not a fresh POST. retrieval_failed permits only the explicit existing-result download retry. 409 idempotency_conflict and 422 image_quote_changed are not transient permission to change keys and try again. Read the current Images state and error reference.
Provider error details and session validation
Provider error bodies are not guaranteed to be passed through unchanged. The decision to expose a provider message is based on its normalized error text, independently of the model, upstream and HTTP status. Unreviewed messages remain hidden behind a safe error response; redaction and the protocol-specific response format still apply. HTTP status and error fields remain useful diagnostics, but they do not select a different disclosure rule for the same normalized text.
An invalid session identifier produces a validation error; correct the field rather than retrying it. An existing recognized session in metadata.user_id is accepted according to the priority of session_id, X-Session-ID, recognized metadata session, prompt_cache_key, then opening content. Different supplied values do not cause a session mismatch error. A plain user identifier is preserved without becoming a conversation ID. A route using this occupied field cannot also insert a managed session; no external sticky binding is promised in that case. Invalid metadata types or duplicate object keys may still produce a validation error on a metadata-session route. Other metadata is preserved. A session identifier is not proof that a timed-out paid request was not accepted. Keep X-Request-ID and inspect the existing request before considering a repeat.
Session forwarding follows the native protocol of the configured connection and does not require a separate receiver or acknowledgement. Client X-Session-ID is accepted at the gateway, but it is not a universal upstream header. Forwarding a session does not guarantee a particular upstream account or a cache hit, and it does not authorize replaying a paid request.
Explicit Images provider failures (14.11.2)
Recognized terminal Images errors use status: failed and a safe error object. image_generation_failed and image_provider_error return HTTP 502 from creation/result reads; invalid_image_request and content_policy_violation use 400; rate_limit_exceeded uses 429. The accepted operation ID and URLs remain in the response. Status GET uses HTTP 200 with the failed operation. Supplier HTTP 200 with an error body is still a generation failure.
billing_review_required describes an unresolved accounting question separately. Do not infer zero cost from a failed generation or automatically resubmit a paid POST. Preserve the original operation ID and Idempotency-Key. See image operations. Arbitrary supplier messages and credentials are not exposed in these error objects.