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": {
"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.
| 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 |
| 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 |
After a non-streaming request has waited about 45 seconds, the server sends 200 plus keep-alive whitespace (see Timeouts). If it fails after that, the status stays 200 and the error is in the body's error field, with the same shape as above. Use the error field to decide success.
For 429 / 500 / 503, use exponential backoff. 400 / 401 / 403 are client errors — retrying will not help, so fix the request first.