Errors

HTTP error codes, response formats, and retry rules.

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	Retry and inspect logs
502/503/504	Upstream unavailable or timed out	Retry with exponential backoff

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. Retry 500, 502, 503, and 504 up to three times with 1/2/4-second backoff. 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; the gateway request history records the terminal failure independently of the wire status. Unknown upstream messages are hidden by default, approved messages may be exposed by administrator policy, and full upstream error exposure is explicit. Internal upstream metadata and temporary raw remain administrator-only. Missing usage after an interrupted stream is unknown/review-required, not an automatic estimate from wire bytes. Preserve the request ID and retry only deliberately after checking partial output.