# 状态码与错误码

一次 API 调用可能同时包含 HTTP 状态、业务错误码和协议级错误。客户端应按固定顺序判断，不能只检查 HTTP `200`，也不能只读取响应体中的 `code`。

## 判断错误的顺序

1. 检查是否取得 HTTP 响应。连接失败、DNS 错误和客户端超时没有 HTTP 状态。
2. 检查 HTTP 状态。非 `2xx` 先按传输或服务错误处理。
3. 检查响应 `Content-Type`，确认解析方式正确。
4. Product 常规 JSON 响应检查业务 `code`；Genesis 检查对应协议的错误对象；A2A 检查 JSON-RPC `error`。
5. 对异步接口，再检查任务是否进入终态以及结果是否可读取。

这套顺序用于错误分类。具体接口公开的错误码、字段和恢复条件仍以接口页为准。

## 常见 HTTP 状态

| 状态 | 含义范围 | 客户端处理 |
| --- | --- | --- |
| `200`–`299` | 请求已由接口接受或处理 | 继续检查业务包络、协议错误和异步状态。 |
| `400` | 请求格式、参数组合或认证凭据冲突 | 根据错误字段修正请求，不原样重试。 |
| `401` | 缺少凭据、凭据无效或认证格式错误 | 检查 Base URL、凭据状态和认证 Header。 |
| `403` | 身份已识别，但无权访问模型、工作区或资源 | 检查模型范围、工作区成员关系、角色和资源授权。 |
| `404` | 路径错误，或资源不存在、已删除、属于其他作用域 | 核对 Base URL、相对路径、工作区和资源 ID。 |
| `409` | 资源状态、版本、名称或幂等请求发生冲突 | 重新读取当前状态；按错误对象决定更新、停止或使用原结果。 |
| `413` | 请求体或上传内容超过接口接受范围 | 缩小请求或文件；只按接口公开限制调整。 |
| `415` | 请求媒体类型不受支持 | 按接口要求修改 `Content-Type` 和请求编码。 |
| `429` | 请求速率、并发、额度或上游容量受到限制 | 读取等待信息并降低压力；只对安全操作进行有界重试。 |
| `500` | 服务处理请求时发生错误 | 保存请求信息；确认操作安全后进行有限重试。 |
| `502`、`503`、`504` | 网关、依赖服务或当前服务暂不可用 | 将其视为可能的临时错误，但写操作先确认是否已经提交。 |

状态码只能确定检查范围，不能单独证明具体原因。例如 `404` 既可能来自错误路径，也可能用于隐藏调用方无权查看的资源。

## Product API 错误

常规 Product 错误通常在 JSON 包络中返回业务错误码和消息：

```json
{
  "code": "ErrParamInvalid",
  "msg": "<ERROR_MESSAGE>",
  "data": null
}
```

处理时：

- 使用 `code` 进行接口文档明确支持的程序分支；
- 将 `msg` 用于诊断和用户提示，不通过匹配自然语言判断错误类型；
- 保留接口公开的 `details`、字段路径或冲突信息；
- 允许部分认证和兼容接口缺少 `data`，或使用数字业务码。

不要维护一张试图覆盖所有实现细节的全局 Product 错误码表。只有公开且稳定、调用方确实需要处理的错误码才进入具体接口参考。

## Genesis 和 A2A 错误

Genesis 的错误对象随协议而定。Chat Completions、Responses 和 Messages 的成功对象不同，其错误字段也应由对应接口页解释；不要先套 Product 包络再解析。

A2A 使用 JSON-RPC。HTTP 成功时仍可能在顶层返回协议错误：

```json
{
  "jsonrpc": "2.0",
  "id": "<REQUEST_ID>",
  "error": {
    "code": <ERROR_CODE>,
    "message": "<ERROR_MESSAGE>"
  }
}
```

收到 `error` 时不要继续从 `result` 读取任务。若请求已经创建任务但后续运行失败，则失败信息可能位于任务状态中，需要使用任务 ID 查询。

## 流式调用中的错误

流式调用存在两个阶段：

- 开始传输前失败：通过 HTTP 状态和普通错误响应判断；
- 已开始传输后失败：通过协议事件、终止状态、解析错误或连接中断判断。

已经收到部分内容后连接中断，不等于请求成功完成。应用应保留已接收数据并标记为中断；只有协议明确支持恢复或应用能识别重复内容时才自动重试。

## 保存诊断信息

错误发生后记录以下脱敏信息：

- 发生时间和时区；
- API 类型、HTTP 方法和不含私有域名的路径形态；
- HTTP 状态、业务或协议错误码；
- 工作区 ID、模型 ID、资源 ID 或任务 ID；
- 响应实际提供的 `X-Request-ID`、`request_id` 或等价关联标识；
- 脱敏后的错误正文；
- 客户端或 SDK 版本；
- 已执行的重试次数。

不要记录访问令牌、API Key、Cookie、数据库密码、临时下载地址或完整业务数据。请求 ID 只有在响应实际返回时才保存，不要假设所有接口都有同名字段。

## 下一步

- [处理限流与重试](rate-limits-retries.md)
- [确认身份认证和工作区作用域](authentication.md)
- [处理分页、异步任务与幂等](pagination-async-idempotency.md)