常见错误

错误响应格式

模型接口的错误以 JSON 返回：

{
  "error": {
    "message": "Insufficient user quota, remaining: ＄0.000000 (request id: 202610230158421013999388268d9d615)",
    "type": "error",
    "code": "insufficient_user_quota"
  }
}

• message 是可读说明，结尾带 (request id: <id>)。同一个 id 也会出现在响应头 X-Oneapi-Request-Id 中，联系技术支持时请一并提供。
• code 是机器可读的错误码。部分错误该字段为空字符串，此时以 HTTP 状态码为准。
• message 会按用户语言设置或 Accept-Language 本地化，且可能调整，程序逻辑请以 HTTP 状态码和 code 为准。

Claude Messages（/v1/messages）改用 {"type": "error", "error": {"type": "...", "message": "..."}}。异步任务接口（/v1/video/generations、/v1/videos、/suno/*）在路由之后产生的错误返回 {"code", "message", "data"}，且其中的 message 不带 request id。

401 Unauthorized

API Key 缺失、无效、已过期、已禁用或额度已用尽：

• 缺少 Authorization 请求头，或没有写成 Bearer sk-...。
• Key 被删除、被禁用或已过期。
• Key 的剩余额度已用完。
• 在模型接口上传了管理密钥（rat_...）；调用模型必须使用 sk- 开头的 API Key。

需要时在控制台 API Keys 页面新建 Key。Key 的额度与有效期见充值与额度。

403 Forbidden

403 有两种完全不同的原因，请先看响应中的 code。

余额或 Key 额度不足

• insufficient_user_quota：账户余额不足以支付本次请求的预估费用，或订阅额度已用完。
• pre_consume_token_quota_failed：Key 的剩余额度不足以支付本次请求的预估费用。

请充值、调高 Key 额度，或降低 max_tokens 让预估费用落在额度内。详见充值与额度。

权限不足

这类错误的 code 通常为空，以错误文案区分具体原因：

• Key 的模型限制不包含该模型（This token has no access to model ...）。
• Key 所在分组对你的账户不可用。
• 来源 IP 不在 Key 的 IP 白名单中（code 为 access_denied）。
• 账户已被禁用。

429 Too Many Requests

触发了请求频率限制。限流按账户计算：同一账户下的所有 Key 共享额度，增加 Key 不会提高上限。被拒绝的请求不计费。

• 使用带随机抖动的指数退避重试。
• 降低并发，或把请求分散到更长时间窗口。
• 429 的响应体可能为空，请以状态码为准，不要依赖错误文案。

限流规则以及上游 429 的重试方式见用量与计费。

503 模型不可用

• code 为 model_not_found，消息类似 “No valid upstream service”：当前没有渠道为你的分组提供该模型。请确认模型 ID 拼写，以及该模型是否对你的账户开放；立即重试同一个请求通常没有意义。

502 / 503 上游错误

• 模型服务商返回的 502 或其他 5xx，在重试全部失败后原样返回。
• code 为 get_channel_failed，消息为 “Upstream service is temporarily unavailable”：渠道背后的上游账号不可用（例如余额或凭据失效）。RouteAPI 会尽量换渠道重试，仍失败时返回这条通用提示、触发内部告警，并可能自动禁用故障渠道；请稍后重试。
• code 为 client_failfast（503）：同一个 API Key 对该模型的请求持续高比例失败，平台为该 Key 与模型组合开启了短时保护窗口。响应会带 Retry-After 和 X-Client-Failfast: 1，请等待后再重试，并先修正失败原因，而不是原样重发。

临时性错误请稍后重试；持续出现时请携带 request id 联系技术支持。