错误码

错误码

错误来源

来源格式如何识别
XSI 自身(认证、权限、额度、限速、请求体)text/plain,单行文本正文为下表中的固定文本
上游服务商上游原样的状态码与 JSON结构与上游官方文档一致
上游不可达502,正文为空连接失败或上游响应无法处理

部署时设置 MASK_ERRORS=true 后,普通 HTTP 代理返回的 ≥ 400 上游错误正文会被替换为 {"error": {"message": "The API is temporarily overloaded.", "status": N}},以免向终端用户暴露上游细节(Realtime 与 Live WebRTC 建会接口不受此开关影响)。

认证

状态码正文处理
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)模型接口:未携带 Key,或 Key 不是 51 位 sk-Xvs 格式(管理接口在同样情况下返回 401 Unauthorized)
401UnauthorizedKey 不存在或已被轮换
429Too many unauthorized requests. Please try again later.该 IP 认证失败过多,被临时封禁 2–15 分钟
403Your account is inactive. Please contact support.账号已停用

访问控制

状态码正文
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.(DeepSeek 计费模型用于错误的接口)

余额与额度

状态码正文说明
401Insufficient balance. ¥<balance> [...]本次检查发现余额低于冻结阈值,账号随即被冻结
429Your API access has been temporarily suspended, please check your plan and billing details.账号已冻结;充值后自动恢复
429You exceeded your current daily quota, please check your plan and billing details. CreditUsedDaily / DailyLimit: ...超出日额度,次日恢复
429You exceeded your current quota, please check your plan and billing details. CreditUsed / HardLimit: ...超出月额度,次月恢复

账号被冻结或超出额度时,GET /dashboard/* 与 /user/balance 仍可访问。

限速

状态码正文恢复时间
429Too many requests, Rate limit <scope> reached, Limit: <rpm>/<rph>/<rpd> (RPM/RPH/RPD).RPM 1 分钟、RPH 1 小时、RPD 次日零点
429Too many requests, Token limit <scope> reached, Limit: <tpm>/<tph>/<tpd> (TPM/TPH/TPD).同上
429Too many requests for model '<model>', Rate limit RPM <n> reached.(RPH、RPD 同理)同上
429TPM exceeded for model '<model>': <n>.(TPH、TPD 同理)同上

Token 限额按已发生的用量累计:本次请求是否放行取决于此前的消耗是否已超过限额。

请求

状态码正文
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(未知的 /dashboard/* 路径)

上游与可用性

状态码正文说明
500No available key该模型对应的 Level 中没有可用 Key(全部禁用或休眠)
502(空)上游不可达
502WebSocket upstream failureWebSocket 握手阶段上游失败
503video generation account unavailable、file account unavailable、No available Realtime provider key绑定的上游账号不可用
503Server is shutting down实例正在优雅关闭

POST 请求遇到可重试的上游错误时,XSI 已在服务端换 Key 重试;客户端收到错误意味着重试已用尽。

管理接口

状态码正文说明
403Management access requires TPD above 800000000. / ... requires sub-user capability. / ... requires balance above <n>.不满足管理者条件
403Only account owner can access this endpoint需要租户所有者
403Forbidden目标不在调用者的账号树内
404User not found、Key not found.目标不存在
409User already exists账号名或邮箱已占用
429API Key was regenerated recently. Please try again later.10 分钟内重复轮换 Key

处理建议

  • 只对 429、502、503 与网络错误做有限次重试,使用指数退避加随机抖动,并遵守 Retry-After。
  • 401、403、413 与额度类 429 不应自动重试,应提示用户检查 Key、权限或余额。
  • 记录状态码与响应正文以便排查,但不要记录完整的 API Key。

相关文档