THE INTEGRATION GUIDE
Error Codes
HTTP status codes give the error category, and the body carries a code for programmatic handling: OpenAI-style endpoints put it in error.code; /v1/messages returns the Anthropic shape, where error.type reflects the status category (e.g. rate_limit_error); the Gemini relay uses error.status. Failures after a stream has started arrive as SSE error events.
HTTP status codes
| HTTP | Cause | What to do |
|---|---|---|
200 | Success | Request completed successfully. |
400 | Bad request | Check the JSON body, required fields, and parameter types. |
401 | Authentication failed | Check the Authorization: Bearer header and confirm the API key is valid, unexpired, and not revoked. |
402 | Insufficient balance | Top up on the Credit page, then retry. |
403 | Access denied | The key is not team-scoped or lacks inference permission, or the model is outside what the key and your organization's policy allow. |
404 | Resource not found | The model ID does not exist or is not enabled for your account, or the requested path / resource (such as a video task ID) was not found. |
413 | Request too large | Shrink the request body, for example by trimming message history or inline images. |
429 | Rate limited | A request-rate, concurrency, or budget limit was hit, or the upstream is rate limiting. Slow down and retry with exponential backoff. |
500 | Server error | Retry with exponential backoff; include the X-Request-Id when contacting support. |
502/503 | Upstream error or service unavailable | The upstream returned an error or is temporarily unavailable; retry after a short delay. |
504 | Upstream timeout | The upstream did not respond in time. Retry later, or reduce max_tokens and the input size. |
Business error codes
These codes appear in the `error.code` field of OpenAI-style responses.
| Code | Description |
|---|---|
invalid_request | Malformed body, missing required field, or parameter out of range. |
context_length_exceeded | The input exceeds the model's context length. |
content_policy_violation | The upstream rejected the request under its content policy. |
invalid_api_key | The API key is invalid or has been revoked. |
insufficient_balance | Account balance is too low; top up to continue. |
permission_denied | The key is not team-scoped and cannot call inference endpoints. |
model_not_entitled | Your API key or organization policy does not allow this model. |
model_not_found | The requested model is not available or the name is incorrect. |
rate_limit_exceeded | Too many requests; slow down and retry with backoff. |
concurrency_limit_exceeded | Too many requests in flight; wait for some to finish. |
budget_exceeded | A budget limit has been reached. |
upstream_rate_limited | The upstream is rate limiting; back off and retry. |
upstream_error | The upstream returned an error. |
upstream_unavailable | The upstream is temporarily unavailable. |
upstream_timeout | The upstream timed out. |
stream_error | The stream failed midway (appears only in SSE events). |
Always include the X-Request-Id response header value when reporting issues.