状态码与错误码

一次 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 包络中返回业务错误码和消息：

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

处理时：

• 使用 code 进行接口文档明确支持的程序分支；

• 将 msg 用于诊断和用户提示，不通过匹配自然语言判断错误类型；

• 保留接口公开的 details、字段路径或冲突信息；

• 允许部分认证和兼容接口缺少 data，或使用数字业务码。

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

Genesis 和 A2A 错误

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

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

{
  "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 只有在响应实际返回时才保存，不要假设所有接口都有同名字段。

下一步

• 处理限流与重试

• 确认身份认证和工作区作用域

• 处理分页、异步任务与幂等

最后更新于 2026 年 8 月 14 日