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

# 错误处理

## 错误处理

当 API 调用失败时，响应通常会包含 HTTP 状态码和 JSON 错误正文。请结合这两部分信息判断：是需要修正请求，还是等待后重试。

### 错误响应格式

失败的请求会返回如下正文：

```json theme={null}
{
  "error": {
    "status": false,
    "type": "invalid_request_error",
    "code": "invalid_request",
    "message": "Invalid parameter: temperature must be between 0 and 2.",
    "msg": "Invalid parameter: temperature must be between 0 and 2.",
    "param": "temperature",
    "traceId": "abc123",
    "retry_after_sec": 30
  }
}
```

| 字段                | 说明                             |
| ----------------- | ------------------------------ |
| type              | 错误类别，是判断处理方式的主要依据              |
| code              | 如果存在，会提供更具体的错误码（某些网关错误可能没有该字段） |
| message / msg     | 面向用户的错误说明；两个字段中可能只返回其中一个       |
| param             | 与错误相关的请求字段（适用时）                |
| traceId           | 排查问题时请提供此字段                    |
| retry\_after\_sec | 存在时，表示建议的重试前等待时间               |

### 首先检查什么

1. **HTTP 状态码**：先判断问题的大类（4xx 表示客户端问题，5xx 表示服务端问题）。
2. **error.type**：再根据错误类型决定处理方式（见下表）。
3. **error.code**：如果存在，可进一步缩小原因范围。
4. **retry\_after\_sec**：如果返回了该字段，重试前请至少等待对应秒数。

### 错误类型与建议操作

| error.type              | HTTP           | error.code                                           | 含义             | 应对方法                          |
| ----------------------- | -------------- | ---------------------------------------------------- | -------------- | ----------------------------- |
| invalid\_request\_error | 400、422、其它 4xx | invalid\_request                                     | 请求正文或参数无效      | 修正请求；不要立即使用相同的负载重试            |
| rate\_limit\_error      | 429            | rate\_limit\_exceeded                                | 后端对此请求进行了限流    | 等待后重试；存在时遵循 retry\_after\_sec |
| RATE\_LIMIT\_EXCEEDED   | 429            | rate\_limit\_exceeded 或 token\_rate\_limit\_exceeded | 达到网关配额或令牌速率限制  | 等待后重试；降低并发或请求速率               |
| MODEL\_PROXY            | 401            | Unauthorized                                         | 身份验证失败         | 核实 API 密钥；在修正凭据前不要重试          |
| BILLING\_DENIED         | 402            | billing\_denied                                      | 超出账户配额或消费限额    | 充值、升级或提升配额；在解决计费问题前重试不会成功     |
| BILLING\_ERROR          | 500            | billing\_error                                       | 临时性计费系统问题      | 稍后重试                          |
| service\_unavailable    | 500、502、503    | service\_unavailable                                 | 临时性服务问题        | 使用退避策略重试                      |
| client\_aborted         | 499            | （通常无）                                                | 客户端在响应完成前断开了连接 | 通常无需操作                        |
| unsupported\_protocol   | 400            | unsupported\_protocol                                | 不支持所请求的协议      | 切换到受支持的协议或接入点                 |
| PROXY\_ERROR            | 400            | （通常无）                                                | 请求无法完成         | 短暂重试可能有帮助；上报时请附上 traceId      |

### 通用重试指南

* **不要重试：** 对于身份验证失败（`401`）、计费拒绝（`402`）和无效请求（`400` / `422`），请先解决根本问题。
* **使用退避策略重试：** 对于速率限制（`429`）和服务端错误（`5xx`），建议采用退避重试；如果响应中包含 `retry_after_sec`，请优先遵循该值。
* **记录 traceId：** 如果错误持续出现，或您无法自行定位问题，请记录错误响应中的 `traceId` 并联系我们以便进一步排查。