Errors
On failure the gateway returns a non-2xx HTTP status code with a unified error body. The message usually ends with a request id to help you locate the entry in the console logs.
Error Structure
{
"error": {
"code": "",
"message": "Error description (request id: 2026053012xxxx)",
"type": "new_api_error"
}
}type indicates the source of the error: the gateway itself, or a passthrough from an upstream provider.
Error Types
| type | Meaning |
|---|---|
new_api_error | Error from the gateway itself (auth, balance, rate limit, parameters, etc.) |
upstream_error | Error returned by an upstream provider (wrapped passthrough) |
openai_error | Error from an OpenAI-protocol upstream |
claude_error | Error from a Claude-protocol upstream |
gemini_error | Error from a Gemini-protocol upstream |
midjourney_error | Midjourney task error |
HTTP Status Codes
| Status | Meaning | Troubleshooting |
|---|---|---|
400 | Bad request | Check the JSON structure, required fields, and whether model is correct |
401 | Unauthenticated / invalid key | Check the auth header and key; confirm it has not been deleted |
403 | Forbidden | The key cannot access this model or group; confirm the model is in range |
429 | Rate limited or insufficient balance | Lower concurrency, retry later, or check your balance |
500 | Internal server error | Contact support with the request id |
503 | Upstream unavailable | Upstream is temporarily unavailable; retry is recommended |
Retry Guidance
Idempotency and Backoff
For 429 / 500 / 503, use exponential backoff. 400 / 401 / 403 are client errors — retrying will not help, so fix the request first.