Errors
Errors
Error sources
| Source | Format | How to recognize it |
|---|
| The Router itself (authentication, permissions, credit, rate limits, request body) | text/plain, single line | The body is one of the fixed texts below |
| Risk-guard block | JSON | error.type is cyber_abuse_guard, see Risk-guard block |
| Model providers | The provider's own status code and JSON | Structure matches the provider's official documentation |
| Upstream unreachable | 502 with an empty body | Connection failure or an unprocessable upstream response |
Some deployments replace the body of upstream errors with status 400 or above in ordinary HTTP requests by {"error": {"message": "The API is temporarily overloaded.", "status": N}} to avoid exposing upstream details; risk-guard responses are not affected, and neither are the Realtime and Live WebRTC creation endpoints.
Authentication
| Status | Body | Action |
|---|
401 | You didn't provide an API key. You need to provide your API key in an Authorization header using Bearer auth (i.e. Authorization: Bearer YOUR_KEY) | Model APIs: no key was sent, or the key is not a 51-character sk-Xvs key (account management APIs return 401 Unauthorized in the same case) |
401 | Unauthorized | The key does not exist or has been rotated |
429 | Too many unauthorized requests. Please try again later. | The IP failed authentication too often and is limited for 2 to 15 minutes |
403 | Your account is inactive. Please contact support. | The account is disabled |
Access control
| Status | Body |
|---|
403 | Access denied: Your IP address <ip> is not authorized. |
403 | Permission restricted: You don't have access to the requested resource '<path>'. |
403 | Access denied: You are not authorized to use the '<model>' model |
400 | The model `<model>` is not available on this endpoint. (a DeepSeek billing model used on the wrong endpoint) |
Risk-guard block
When the risk guard is enabled and a model provider returns a cybersecurity usage-policy response (error code cyber_policy, or a safety_buffering event marked with the cyber use case), the request that triggered it is returned to you unchanged and the account is then temporarily blocked for 36 hours. During the block, every request except GET /v1/models, GET /models, and /dashboard/* (including later requests on WebSocket and realtime sessions) returns:
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error": {
"message": "User is temporarily blocked after a Cyber abuse policy response",
"type": "cyber_abuse_guard",
"code": "temporary_blocked",
"user_id": 42,
"until_at": "2026-11-21T18:00:00+08:00"
}
}
until_at is the time the block expires (RFC 3339). The block applies per account, retrying does not shorten it, and it lifts automatically on expiry. To have it lifted earlier, contact your service provider.
Balance and credit
| Status | Body | Notes |
|---|
401 | Insufficient balance. $<balance> [...] | This check found the balance below the freeze threshold, and the account is frozen immediately |
429 | Your API access has been temporarily suspended, please check your plan and billing details. | The account is frozen; it recovers automatically after a top-up |
429 | You exceeded your current daily quota, please check your plan and billing details. CreditUsedDaily / DailyLimit: ... | Daily credit exceeded; recovers the next day |
429 | You exceeded your current quota, please check your plan and billing details. CreditUsed / HardLimit: ... | Monthly credit exceeded; recovers next month |
GET /dashboard/* and /user/balance remain available when an account is frozen or over its credit. When a subscription account (role 3) exceeds its daily or monthly credit and has a pay-as-you-go balance, it switches to that balance automatically and the credit errors above no longer apply.
Rate limits
| Status | Body | Recovery |
|---|
429 | Too many requests, Rate limit <scope> reached, Limit: <rpm>/<rph>/<rpd> (RPM/RPH/RPD). | RPM 1 minute, RPH 1 hour, RPD next midnight |
429 | Too many requests, Token limit <scope> reached, Limit: <tpm>/<tph>/<tpd> (TPM/TPH/TPD). | Same as above |
429 | Too many requests for model '<model>', Rate limit RPM <n> reached. (same for RPH, RPD) | Same as above |
429 | TPM exceeded for model '<model>': <n>. (same for TPH, TPD) | Same as above |
Token limits accumulate on usage that has already occurred: whether a request is admitted depends on whether earlier consumption has already exceeded the limit. Accounts with role 0 or 1 skip the daily and monthly credit checks and rate limits.
Requests
| Status | Body |
|---|
413 | request body too large |
400 | Error reading request body: ..., error parsing multipart form: ..., Error creating <encoding> reader: ... |
400 | invalid video request_id |
400 | invalid or unavailable Codex file; upload it again with the current account, plus other Codex file reference validation messages; see Router API |
400 | Live sessions do not accept query parameters; put the model in session.start, Public Live sessions require gpt-live-1 |
404 | 404 page not found (unknown /dashboard/* paths) |
Upstream and availability
| Status | Body | Notes |
|---|
500 | No available key | No available upstream in the Level for this model |
502 | (empty) | Upstream unreachable |
502 | WebSocket upstream failure | Upstream failed during the WebSocket handshake |
503 | video generation account unavailable, file account unavailable, No available Codex file account, No available Realtime provider key | The bound upstream account is unavailable |
503 | No OpenAI Live project key at the configured model level | The upstream of your plan is not the official OpenAI API, so /v1/live/sessions is unavailable; on a Codex plan use /v1/live, see WebSocket and Realtime APIs |
503 | request body memory budget exhausted | The total request-body volume being processed has reached its limit; retry shortly |
503 | Server is shutting down | The instance is shutting down gracefully |
503 | {"error": {"code": "codex_models_unavailable", ...}} | The native model catalog for Codex clients is temporarily unavailable |
When a POST request hits a retryable upstream error, the Router has already retried on other upstreams server-side; receiving the error means the retries were exhausted.
Account management APIs
| Status | Body | Notes |
|---|
403 | Management access requires TPD above 800000000. / ... requires sub-user capability. / ... requires balance above <n>. | Manager conditions not met |
403 | Forbidden | The target is not in your account tree |
404 | User not found | The target does not exist |
409 | User already exists | The account name or email is taken |
429 | API Key was regenerated recently. Please try again later. | Key rotated again within 10 minutes |
Recommendations
- Retry only
429, 502, 503, and network errors, a limited number of times, with exponential backoff and jitter, and honor Retry-After when present. - Do not retry
401, 403, 413, or credit-related 429 automatically; ask the user to check the key, permissions, or balance. - Stop retrying after a risk-guard block and wait for
until_at. - Log the status code and response body for diagnosis, but never the full API Key.