OpenAI 兼容 API 与 Anthropic 兼容 API 的错误返回与处理建议。

OpenAI 兼容（/v1/*）

{
  "error": {
    "message": "可读说明",
    "type": "invalid_request_error",
    "param": "messages[0].tool_call_id",
    "code": "insufficient_balance"
  }
}
字段含义
message主要说明
type如 invalid_request_error、rate_limit_error
param校验失败时的 JSON 路径
code机器可读码（如 insufficient_balance、quota_exceeded、ip_not_allowed、upstream_rate_limited）

部分响应可能含 error.gateway 结构化字段。

Anthropic 兼容（/anthropic/v1/*）

{
  "type": "error",
  "error": { "type": "authentication_error", "message": "..." },
  "request_id": "req_..."
}

提工单时请记录 request_id。

HTTP 状态码

状态码含义客户端建议
400请求体或内容不合法修正后重试，勿盲目重放
401密钥缺失/错误/过期更换密钥，检查 Bearer / x-api-key
403策略：模型、余额、IP、上游密钥等改配置或计费，通常勿重试
429限流指数退避 + 抖动
502/503上游或网关瞬时故障有限重试
504超时加大客户端超时，检查请求体大小

重试建议

  1. 可重试： 429、502、503、504 及短暂网络错误。
  2. 勿原样重试： 400、401、多数 403。
  3. 有副作用的 tool 调用请在业务层做幂等。
  4. 建议上限 3–5 次，退避 1s 起、封顶约 60s。

关联追踪

每次请求建议携带 x-trace-id；工单附上时间戳、model 与脱敏请求头（见 支持信息、请求关联）。