错误码与处理 - FortAPI

请求出错时，FortAPI 用 HTTP 状态码 + 一个 JSON 错误体告诉你原因。错误体的形状取决于你用的协议。

错误体格式

OpenAI 协议（/v1/chat/completions 等）：

{
  "error": {
    "message": "用户额度不足 (request id: 2025...-abc)",
    "type": "insufficient_quota",
    "param": "",
    "code": "insufficient_user_quota"
  }
}

Claude 协议（/v1/messages）：

{
  "type": "error",
  "error": {
    "type": "overloaded_error",
    "message": "上游暂时过载，请稍后重试"
  }
}

message 末尾通常带 request id。联系支持时附上它，能最快定位到那条请求的日志。

状态码

状态码	含义	怎么办
`401`	鉴权失败：key 缺失、拼错、已禁用或已删除	确认用的是 FortAPI 令牌（`sk-...`），没有多余空格/换行；在控制台「令牌」确认它仍启用
`403`	额度不足、令牌/账号被禁、分组无权访问该模型	充值，或换一个有权限的模型；确认令牌的「可访问模型」白名单没排除它（额度不足是 403，不是 402）
`404`	模型不存在，或请求路径写错	核对模型名（以主站价格页为准）；OpenAI 协议 base_url 带 `/v1`，Anthropic SDK 的 `ANTHROPIC_BASE_URL` 不带 `/v1`
`429`	触发限流（请求太频繁）	退避后重试，见限流
`500`	服务内部错误	多为偶发，稍后重试；持续出现请带 request id 联系支持
`503`	暂时没有可用渠道，或系统过载	稍后重试或换模型；持续出现请联系支持
`529`	上游厂商（如 Anthropic）过载，原样透传，`type` 为 `overloaded_error`	这是上游的临时状态，指数退避重试通常即可恢复

区分错误来自哪一层

FortAPI 自己返回的错误，type 多为 new_api_error 或标准类型（如 insufficient_quota、invalid_request_error），message 常为中文。
上游厂商返回的错误（如 rate_limit_error、overloaded_error），FortAPI 会原样透传其状态码与类型，必要时按渠道做重试。看到 overloaded_error / rate_limit_error 一般是上游侧的问题。

重试建议

对 429 / 500 / 503 / 529 这类临时错误，用指数退避重试（如 1s、2s、4s…，加一点随机抖动），别原地高频重试，否则更容易撞限流。401 / 403 / 404 是配置类错误，重试无用，先按上表修配置。