Errors

Errors

Error sources

SourceFormatHow to recognize it
The Router itself (authentication, permissions, credit, rate limits, request body)text/plain, single lineThe body is one of the fixed texts below
Risk-guard blockJSONerror.type is cyber_abuse_guard, see Risk-guard block
Model providersThe provider's own status code and JSONStructure matches the provider's official documentation
Upstream unreachable502 with an empty bodyConnection 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

StatusBodyAction
401You 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)
401UnauthorizedThe key does not exist or has been rotated
429Too many unauthorized requests. Please try again later.The IP failed authentication too often and is limited for 2 to 15 minutes
403Your account is inactive. Please contact support.The account is disabled

Access control

StatusBody
403Access denied: Your IP address <ip> is not authorized.
403Permission restricted: You don't have access to the requested resource '<path>'.
403Access denied: You are not authorized to use the '<model>' model
400The 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

StatusBodyNotes
401Insufficient balance. $<balance> [...]This check found the balance below the freeze threshold, and the account is frozen immediately
429Your API access has been temporarily suspended, please check your plan and billing details.The account is frozen; it recovers automatically after a top-up
429You exceeded your current daily quota, please check your plan and billing details. CreditUsedDaily / DailyLimit: ...Daily credit exceeded; recovers the next day
429You 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

StatusBodyRecovery
429Too many requests, Rate limit <scope> reached, Limit: <rpm>/<rph>/<rpd> (RPM/RPH/RPD).RPM 1 minute, RPH 1 hour, RPD next midnight
429Too many requests, Token limit <scope> reached, Limit: <tpm>/<tph>/<tpd> (TPM/TPH/TPD).Same as above
429Too many requests for model '<model>', Rate limit RPM <n> reached. (same for RPH, RPD)Same as above
429TPM 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

StatusBody
413request body too large
400Error reading request body: ..., error parsing multipart form: ..., Error creating <encoding> reader: ...
400invalid video request_id
400invalid or unavailable Codex file; upload it again with the current account, plus other Codex file reference validation messages; see Router API
400Live sessions do not accept query parameters; put the model in session.start, Public Live sessions require gpt-live-1
404404 page not found (unknown /dashboard/* paths)

Upstream and availability

StatusBodyNotes
500No available keyNo available upstream in the Level for this model
502(empty)Upstream unreachable
502WebSocket upstream failureUpstream failed during the WebSocket handshake
503video generation account unavailable, file account unavailable, No available Codex file account, No available Realtime provider keyThe bound upstream account is unavailable
503No OpenAI Live project key at the configured model levelThe 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
503request body memory budget exhaustedThe total request-body volume being processed has reached its limit; retry shortly
503Server is shutting downThe 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

StatusBodyNotes
403Management access requires TPD above 800000000. / ... requires sub-user capability. / ... requires balance above <n>.Manager conditions not met
403ForbiddenThe target is not in your account tree
404User not foundThe target does not exist
409User already existsThe account name or email is taken
429API 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.