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

# 错误码与处理

> 了解模型 API 的常见 HTTP 错误、处理方式与重试建议。

ApiGo 模型 API 使用 HTTP 状态码表示请求结果。错误响应的具体字段会遵循你所调用 endpoint 的兼容协议，但状态码的含义和建议处理方式保持一致。

不要依赖完整的错误文案进行程序判断。优先使用 HTTP 状态码，以及响应中存在的结构化错误类型或错误代码。

## HTTP 状态码

| 状态码   | 含义                           | 建议处理                          |
| ----- | ---------------------------- | ----------------------------- |
| `400` | 请求参数无效、格式错误，或当前模型不支持该请求。     | 修改请求后再重试。                     |
| `401` | API 密钥缺失、无效或已停用。             | 检查鉴权方式和 API 密钥。               |
| `402` | 账户余额不足。部分兼容协议会使用该状态码。        | 充值后再发起请求。                     |
| `403` | API 密钥有效，但没有执行该请求的权限。        | 检查模型权限、IP 白名单和密钥配置。           |
| `404` | 请求的模型、任务或资源不存在，或当前密钥无权访问。    | 检查模型名称、资源 ID 和调用时使用的 API 密钥。  |
| `429` | 命中请求频率限制、账户余额不足或 API 密钥用量限制。 | 根据错误内容决定退避重试、充值、调整限额或等待下一个周期。 |
| `503` | ApiGo 或上游服务暂时无法处理请求。         | 使用指数退避和随机抖动重试。                |

## 理解 `402` 和 `429`

`402` 和 `429` 都可能表示当前请求受到用量或容量约束，但处理方式不同：

* **请求频率或并发限制**：降低请求速度，并使用指数退避重试。
* **账户余额不足**：充值后再重试。持续自动重试不会解决问题。
* **API 密钥用量限制**：提高该密钥的限额，或等待当前限额周期结束。

不同 endpoint 的结构化错误字段可能不同。请结合 HTTP 状态码、响应中的错误类型或错误代码，以及错误文案判断具体原因。

更多限流建议请参阅[速率限制](/api-reference/guide/rate-limits)。

## 响应格式

错误响应会遵循所调用 endpoint 的兼容协议，而不是所选模型或上游服务的协议。随着 ApiGo 接入新的模型或上游服务，你不需要为每个 provider 增加新的错误处理分支。

不同兼容协议可能使用 `type`、`code` 或 `status` 等不同字段。它们不是一套跨 endpoint 通用的枚举。

| 信息         | 稳定性与用法                                                  |
| ---------- | ------------------------------------------------------- |
| HTTP 状态码   | 作为第一层处理依据。                                              |
| 结构化错误类型或代码 | 按当前 endpoint 的 API 定义或 SDK 类型处理，不要跨 endpoint 假设字段名和值相同。 |
| 错误文案       | 用于展示和排障，不要依赖完整文案进行程序判断。                                 |
| 补充排障信息     | 可能不存在或被脱敏，不应作为业务逻辑依赖。                                   |

使用对应 endpoint 的 API 定义或 SDK 类型处理具体响应结构。

## 流式请求

流式请求可能以两种方式失败：

* 如果错误发生在流开始之前，API 会返回正常的 HTTP 错误状态和错误响应体。
* 如果错误发生在流开始之后，HTTP 状态可能已经是 `200`，错误会作为事件出现在数据流中。

客户端应持续读取数据流直到正常结束，并将流中的错误事件视为请求失败。不要只根据最初的 HTTP `200` 判断流式请求成功。

## 重试与排障

* 不要自动重试 `400`、`401`、`402`、`403` 或 `404`，除非你已经修正对应问题。
* 只有在 `429` 表示请求频率限制时才自动重试；余额或密钥限额问题需要先处理账户配置。
* 对 `503` 使用有限次数的指数退避重试，并加入随机抖动，避免大量客户端同时重试。
* 记录请求时间、endpoint、HTTP 状态码和结构化错误类型。响应中存在 [`x-apigo-request-id`](/api-reference/guide/request-ids) 时也一并记录。
* 不要在日志或工单中记录完整的 API 密钥。

为保护平台和上游服务信息，部分错误会被归一化为通用的 `503`。这类响应不会公开内部或上游的具体失败原因。