错误码与错误处理

先判断哪里失败

1. 记录实际 HTTP 状态、请求方法和路径。HTTP 状态与响应体中的应用错误码是两层信息，不要相互替代。
2. 根据所调用的协议读取错误字段。平台原生、OpenAI、Claude 和 Gemini 的结构不完全相同。
3. 流式请求还要检查错误事件与结束状态；异步任务还要检查任务的 status。HTTP 200 不代表生成一定成功。
4. 根据下表修正请求或决定是否重试。message 用于解释，不是稳定枚举，不要匹配其文案来驱动程序分支。

平台错误码枚举

以下是平台应用错误码的完整枚举。名称用于查询，响应中的 code 使用数字。 “常见 HTTP”是排查参考，不是所有接口的固定映射；以实际 HTTP 状态和响应体为准。 上游原样返回的 code 不一定属于此枚举。

只有 HTTP 429 时，无法可靠区分频率限制与并发限制；有明确的数字错误码时再细分。 模型标识可通过 模型列表核对，不要自行改写 model 值。

按协议读取错误

以下示例展示常见的平台生成结构，不保证每次失败都使用同一结构。 认证阶段的错误可能由不同处理层返回，上游透传响应也可能保留自己的结构、字符串错误码或类型。 先识别实际响应形状，再解析；无法识别时保留原始字段和 HTTP 状态，不要强行转换。

平台原生接口

通常读取 error.code 和 error.message。requestId 可能缺失。

{
  "success": false,
  "error": {
    "code": 10000,
    "message": "Bad request"
  },
  "requestId": "req_example"
}

部分错误可能使用顶层 code、message；客户端应容忍这种差异，不要仅凭是否存在 error 对象判断成功。 参数校验响应也可能不含数字错误码；缺失时按未知处理，不要自行补造。

OpenAI 兼容接口

平台生成的常见错误使用顶层 code、message 和 type，不是必须包在 error 中。

{
  "code": 40000,
  "message": "Insufficient credit",
  "type": "api_error"
}

type 是协议类别，code 才是此结构中的平台数字错误码。单凭 api_error 不能确定是否值得重试。 上游透传或流式错误可能使用嵌套的 error，按实际协议响应处理。 参见 Chat Completions和 Responses。

Claude 兼容接口

常见结构的顶层 type 为 error，具体类别位于 error.type，说明位于 error.message。 此结构不包含平台数字 code，不要补造一个数字错误码。

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens must be a positive safe integer"
  }
}

平台本地产生的 Claude 错误类型如下；这不是上游所有错误类型的完整枚举。

参见 Claude Messages。

Gemini 风格错误

收到 Gemini 风格响应时，读取 error.code、error.message 和 error.status。 这里的 status 是字符串类别，不是 HTTP 状态，也不是异步任务状态。

{
  "error": {
    "code": 10000,
    "message": "Bad request",
    "status": "INVALID_ARGUMENT"
  }
}

平台生成的此类错误使用平台数字 code。本地字符串 status 映射如下，不是上游全部状态的枚举。

503 优先使用 UNAVAILABLE，不归入 INTERNAL。上游响应可能采用不同的 code 和 status 语义，不要把所有 Gemini 数字码直接套入平台错误码表。

安全重试

响应包含有效的 Retry-After 时，优先遵守其等待时间；不能假设每次都会返回该头。 自动重试非幂等生成请求可能重复执行并产生额外费用。本页不承诺通用幂等键支持，不要假设自行添加 Idempotency-Key 就能去重。

已获得 jobId 时，先查询现有任务，不要重新创建。未获得 jobId 且结果不确定时，保留请求标识和时间以供排查。

流式与异步任务

SSE 流式请求

SSE 开始后，HTTP 状态可能仍为 200，后续失败通过流中的错误事件或错误载荷报告。 解析所用协议的事件与数据，检查是否正常完成；收到错误或连接异常中断时，不要把已收到的部分文本或图片当作完整成功结果。 不同接口的事件名称和载荷不同，不要只检测一种固定 error 字段，也不要把“收到任意文本”作为成功条件。

异步任务

创建响应返回 data.jobId 只表示已受理，不表示生成完成。 查询任务的 HTTP 成功也只表示查询成功，仍须读取任务的 data.status：

• PENDING、CONNECT、PROCESSING：继续按 Jobs 文档轮询。
• COMPLETED：读取 outputResult。
• FAILED、CANCELLED：停止轮询，保留任务 ID 和脱敏后的返回信息再排查。

失败详情可能位于 data.outputResult.error；该字段是可选的，不保证每次失败都有。 仅当创建响应明确返回 jobId 时使用 Jobs；直接返回 JSON 或 SSE 结果的接口不要套用任务轮询流程。

用户与 AI 诊断清单

向客服或 AI 提供以下脱敏信息。字段缺失就填写 unknown；没有收到 HTTP 响应时，HTTP 状态也填写 unknown。 保留字段路径及原始值类型，例如 error.code: 10000 (number) 或 error.code: "invalid_api_key" (string)。 不要把字符串 code 自动转成平台数字码，不要根据 message、HTTP 状态或模型名称补造缺失字段。

time_with_timezone: unknown
method: unknown
path_without_query: unknown
model: unknown
stream: unknown
http_status: unknown
error_code_path_value_and_type: unknown
error_type_path_and_value: unknown
protocol_status_path_and_value: unknown
sanitized_message: unknown
request_id_from_body_or_X-Request-ID: unknown
job_id: unknown
job_status: unknown
retry_after: unknown
retry_count_and_delays: unknown
received_partial_output: unknown

requestId 可从响应体或 X-Request-ID 响应头获取（如有）；jobId 按字符串保留，避免长数字精度丢失。 提供最小、已脱敏的请求参数即可。删除 API Key、Token、Cookie、完整认证头、个人信息、私密提示词与输入文件内容； 删除 URL 查询参数及带签名或访问凭据的输入、输出 URL。不要直接粘贴未经检查的完整请求日志。

AI 排查时应区分“实际观察到的字段”和“可能原因”，列出缺失信息；信息不足时不要推断请求已成功、未执行或未产生费用。