Errors
Errors
Error sources
| Source | Format | How to identify |
|---|
| XSI itself (authentication, permissions, credit, rate limits, request body) | text/plain, single line | The body is one of the fixed strings in the tables below |
| Upstream provider | The upstream's status code and JSON, unchanged | Structure matches the upstream's official documentation |
| Upstream unreachable | 502 with an empty body | Connection 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
| 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 provided, or the key is not in the 51-character sk-Xvs format (management APIs return 401 Unauthorized in the same cases) |
401 | Unauthorized | The key does not exist or has been rotated |
429 | Too many unauthorized requests. Please try again later. | Too many authentication failures from this IP; temporarily blocked for 2β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) |
Balance and credit
| Status | Body | Notes |
|---|
401 | Insufficient balance. Β₯<balance> [...] | This check found the balance below the suspension threshold, and the account was suspended |
429 | Your API access has been temporarily suspended, please check your plan and billing details. | The account is suspended; it resumes automatically after a top-up |
429 | You exceeded your current daily quota, please check your plan and billing details. CreditUsedDaily / DailyLimit: ... | Daily limit exceeded; resets the next day |
429 | You 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
| 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. (likewise for RPH and RPD) | Same as above |
429 | TPM 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
| 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 | 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/* path) |
Upstream and availability
| Status | Body | Notes |
|---|
500 | No available key | The Level for this model has no available keys (all disabled or sleeping) |
502 | (empty) | Upstream unreachable |
502 | WebSocket upstream failure | The upstream failed during the WebSocket handshake |
503 | video generation account unavailable, file account unavailable, No available Realtime provider key | The bound upstream account is unavailable |
503 | Server is shutting down | The 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
| Status | Body | Notes |
|---|
403 | Management access requires TPD above 800000000. / ... requires sub-user capability. / ... requires balance above <n>. | Manager requirements not met |
403 | Only account owner can access this endpoint | Requires a tenant owner |
403 | Forbidden | The target is outside the caller's account tree |
404 | User not found, Key not found. | The target does not exist |
409 | User already exists | Account name or email already in use |
429 | API 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.