Error Codes and Retries

When an error occurs, the API returns a non-2xx status code, and the response body is JSON:

{
  "error": {
    "message": "error description",
    "type": "invalid_request_error",
    "code": "..."
  }
}

Common Error Codes

HTTP Status	Common Cause	Recommended Action
400	Parameter error, invalid request body format	Verify parameters and JSON format
401	Missing / invalid key	Check Authorization: Bearer sk-...
403	Token disabled, model group not authorized	Check token status and group in the console
404	Model name does not exist or is not available	See Model Overview
413	Request body too large (context limit exceeded)	Reduce messages or switch to a long-context model
429	Rate limit exceeded or insufficient quota	Retry with backoff; see Rate Limits and 429
500 / 502 / 503	Upstream model instability	Retry after a short backoff; the gateway will automatically switch to an available upstream

Retry Recommendations

• For 429 / 5xx, use exponential backoff + jitter: e.g. 1s, 2s, 4s, up to 3–5 retries;
• 400 / 401 / 403 are deterministic errors; retries are meaningless and the request should be fixed first;
• For idempotent scenarios (such as image generation), confirm the final status of the previous request before resubmitting to avoid duplicate charges;
• In production, it is recommended to log the response headers and error.message to help identify which part returned the error.

Tip

The gateway has built-in multi-upstream redundancy and automatic failover: when a single upstream becomes unstable, traffic is automatically rerouted, and most 5xx errors can be resolved with a short backoff and retry.