错误码
错误码
错误来源
| 来源 | 格式 | 如何识别 |
|---|
| XSI 自身(认证、权限、额度、限速、请求体) | text/plain,单行文本 | 正文为下表中的固定文本 |
| 上游服务商 | 上游原样的状态码与 JSON | 结构与上游官方文档一致 |
| 上游不可达 | 502,正文为空 | 连接失败或上游响应无法处理 |
部署时设置 MASK_ERRORS=true 后,普通 HTTP 代理返回的 ≥ 400 上游错误正文会被替换为 {"error": {"message": "The API is temporarily overloaded.", "status": N}},以免向终端用户暴露上游细节(Realtime 与 Live WebRTC 建会接口不受此开关影响)。
认证
| 状态码 | 正文 | 处理 |
|---|
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) | 模型接口:未携带 Key,或 Key 不是 51 位 sk-Xvs 格式(管理接口在同样情况下返回 401 Unauthorized) |
401 | Unauthorized | Key 不存在或已被轮换 |
429 | Too many unauthorized requests. Please try again later. | 该 IP 认证失败过多,被临时封禁 2–15 分钟 |
403 | Your account is inactive. Please contact support. | 账号已停用 |
访问控制
| 状态码 | 正文 |
|---|
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.(DeepSeek 计费模型用于错误的接口) |
余额与额度
| 状态码 | 正文 | 说明 |
|---|
401 | Insufficient balance. ¥<balance> [...] | 本次检查发现余额低于冻结阈值,账号随即被冻结 |
429 | Your API access has been temporarily suspended, please check your plan and billing details. | 账号已冻结;充值后自动恢复 |
429 | You exceeded your current daily quota, please check your plan and billing details. CreditUsedDaily / DailyLimit: ... | 超出日额度,次日恢复 |
429 | You exceeded your current quota, please check your plan and billing details. CreditUsed / HardLimit: ... | 超出月额度,次月恢复 |
账号被冻结或超出额度时,GET /dashboard/* 与 /user/balance 仍可访问。
限速
| 状态码 | 正文 | 恢复时间 |
|---|
429 | Too many requests, Rate limit <scope> reached, Limit: <rpm>/<rph>/<rpd> (RPM/RPH/RPD). | RPM 1 分钟、RPH 1 小时、RPD 次日零点 |
429 | Too many requests, Token limit <scope> reached, Limit: <tpm>/<tph>/<tpd> (TPM/TPH/TPD). | 同上 |
429 | Too many requests for model '<model>', Rate limit RPM <n> reached.(RPH、RPD 同理) | 同上 |
429 | TPM exceeded for model '<model>': <n>.(TPH、TPD 同理) | 同上 |
Token 限额按已发生的用量累计:本次请求是否放行取决于此前的消耗是否已超过限额。
请求
| 状态码 | 正文 |
|---|
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(未知的 /dashboard/* 路径) |
上游与可用性
| 状态码 | 正文 | 说明 |
|---|
500 | No available key | 该模型对应的 Level 中没有可用 Key(全部禁用或休眠) |
502 | (空) | 上游不可达 |
502 | WebSocket upstream failure | WebSocket 握手阶段上游失败 |
503 | video generation account unavailable、file account unavailable、No available Realtime provider key | 绑定的上游账号不可用 |
503 | Server is shutting down | 实例正在优雅关闭 |
POST 请求遇到可重试的上游错误时,XSI 已在服务端换 Key 重试;客户端收到错误意味着重试已用尽。
管理接口
| 状态码 | 正文 | 说明 |
|---|
403 | Management access requires TPD above 800000000. / ... requires sub-user capability. / ... requires balance above <n>. | 不满足管理者条件 |
403 | Only account owner can access this endpoint | 需要租户所有者 |
403 | Forbidden | 目标不在调用者的账号树内 |
404 | User not found、Key not found. | 目标不存在 |
409 | User already exists | 账号名或邮箱已占用 |
429 | API Key was regenerated recently. Please try again later. | 10 分钟内重复轮换 Key |
处理建议
- 只对
429、502、503 与网络错误做有限次重试,使用指数退避加随机抖动,并遵守 Retry-After。 401、403、413 与额度类 429 不应自动重试,应提示用户检查 Key、权限或余额。- 记录状态码与响应正文以便排查,但不要记录完整的 API Key。
相关文档