> ## 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.

# 错误处理

> 了解算秩 Model Inference API 的错误响应格式、HTTP 状态码、错误类型、重试策略和 traceId 排查方法。

当 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**：如果返回了该字段，重试前请至少等待对应秒数。

## 错误类型与建议操作

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

## 通用建议

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