Errors and troubleshooting
Unsuccessful responses generally use a common error object. Retain the HTTP status, error.type, error.message, and the X-Request-Id response header.
Error response shape
JSON
{
"error": {
"message": "model is required",
"type": "invalid_request_error"
}
}Common status codes
| Status | Meaning | Suggested action |
|---|---|---|
400 | Invalid request shape or parameters | Check JSON or multipart formatting, required fields, and capabilities of the selected model. |
401 | Missing, invalid, or expired API key | Check the authentication header, key value, and expiry; do not quote the Bearer value. |
403 | API key restrictions rejected the request | Check the model allowlist, IP allowlist, and other key restrictions. |
404 | Model or asynchronous task unavailable | Use a model ID returned by /v1/models and confirm the task belongs to the current account. |
429 | Rate limit or insufficient quota | Reduce request frequency and check key limits, account quota, and wallet state before retrying with backoff. |
500 | Internal platform failure | Retain X-Request-Id, retry later, and locate the request in the console records. |
502 | Upstream Provider request failed | Check model route availability and retry a limited number of times with backoff. |
503 | Service or model route temporarily unavailable | Retry later; if persistent, select another available model or inspect Provider status. |
Request ID
The gateway returns a request ID in the X-Request-Id response header. Retain it when reporting an issue and use the signed-in console usage or request records to locate the call.
Streaming requests
An error after a stream starts may arrive as an SSE event instead of a new HTTP error response. Handle non-2xx responses, in-stream error events, connection timeouts, and interrupted streams. Idle connections may receive comment heartbeats.
Troubleshooting order
- Confirm the Base URL ends in /v1 and the endpoint does not repeat /v1.
- Use /v1/models to verify both the API key and model ID.
- Start with a minimal non-streaming request, then add optional fields one at a time.
- Inspect the HTTP status, error.type, error.message, and X-Request-Id.
- Check quota, key restrictions, and request records in the console.