> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fortapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 错误码与处理

> FortAPI 返回的 HTTP 状态码、错误体格式，以及每类错误怎么办

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

## 错误体格式

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

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

**Claude 协议**（`/v1/messages`）：

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

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

## 状态码

| 状态码   | 含义                                                   | 怎么办                                                                                       |
| ----- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `401` | 鉴权失败：key 缺失、拼错、已禁用或已删除                               | 确认用的是 FortAPI 令牌（`sk-...`），没有多余空格/换行；在控制台 **「令牌」** 确认它仍启用                                 |
| `403` | 额度不足、令牌/账号被禁、分组无权访问该模型                               | 充值，或换一个有权限的模型；确认令牌的「可访问模型」白名单没排除它（**额度不足是 403，不是 402**）                                   |
| `404` | 模型不存在，或请求路径写错                                        | 核对模型名（以主站价格页为准）；OpenAI 协议 base\_url 带 `/v1`，Anthropic SDK 的 `ANTHROPIC_BASE_URL` 不带 `/v1` |
| `429` | 触发限流（请求太频繁）                                          | 退避后重试，见 [限流](/zh/rate-limits)                                                             |
| `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` 是**配置类**错误，重试无用，先按上表修配置。