Errors

Errors

Error sources

SourceFormatHow to identify
XSI itself (authentication, permissions, credit, rate limits, request body)text/plain, single lineThe body is one of the fixed strings in the tables below
Upstream providerThe upstream's status code and JSON, unchangedStructure matches the upstream's official documentation
Upstream unreachable502 with an empty bodyConnection failure, or the upstream response could not be processed

When a deployment sets MASK_ERRORS=true, the body of upstream errors β‰₯ 400 returned by the regular HTTP proxy is replaced with {"error": {"message": "The API is temporarily overloaded.", "status": N}} so that upstream details are not exposed to end users (the Realtime and Live WebRTC session-creation endpoints are not affected by this switch).

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 provided, or the key is not in the 51-character sk-Xvs format (management APIs return 401 Unauthorized in the same cases)
401UnauthorizedThe key does not exist or has been rotated
429Too many unauthorized requests. Please try again later.Too many authentication failures from this IP; temporarily blocked for 2–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)

Balance and credit

StatusBodyNotes
401Insufficient balance. Β₯<balance> [...]This check found the balance below the suspension threshold, and the account was suspended
429Your API access has been temporarily suspended, please check your plan and billing details.The account is suspended; it resumes automatically after a top-up
429You exceeded your current daily quota, please check your plan and billing details. CreditUsedDaily / DailyLimit: ...Daily limit exceeded; resets the next day
429You exceeded your current quota, please check your plan and billing details. CreditUsed / HardLimit: ...Monthly limit exceeded; resets the next month

When an account is suspended or over its credit limit, GET /dashboard/* and /user/balance remain accessible.

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. (likewise for RPH and RPD)Same as above
429TPM exceeded for model '<model>': <n>. (likewise for TPH and TPD)Same as above

Token limits accumulate on usage already incurred: whether a request is allowed depends on whether prior consumption has already exceeded the limit.

Requests

StatusBody
413request body too large
400Error reading request body: ..., error parsing multipart form: ..., Error creating <encoding> reader: ...
400invalid video request_id
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/* path)

Upstream and availability

StatusBodyNotes
500No available keyThe Level for this model has no available keys (all disabled or sleeping)
502(empty)Upstream unreachable
502WebSocket upstream failureThe upstream failed during the WebSocket handshake
503video generation account unavailable, file account unavailable, No available Realtime provider keyThe bound upstream account is unavailable
503Server is shutting downThe instance is shutting down gracefully

When a POST request hits a retryable upstream error, XSI has already retried with other keys on the server side; an error reaching the client means retries are exhausted.

Management APIs

StatusBodyNotes
403Management access requires TPD above 800000000. / ... requires sub-user capability. / ... requires balance above <n>.Manager requirements not met
403Only account owner can access this endpointRequires a tenant owner
403ForbiddenThe target is outside the caller's account tree
404User not found, Key not found.The target does not exist
409User already existsAccount name or email already in use
429API Key was regenerated recently. Please try again later.Key rotated again within 10 minutes

Handling recommendations

  • Retry only 429, 502, 503 and network errors, a limited number of times, with exponential backoff and random jitter, and honor Retry-After.
  • Do not automatically retry 401, 403, 413 or credit-related 429 errors; prompt the user to check their key, permissions or balance.
  • Log status codes and response bodies for troubleshooting, but never log full API keys.