AI API 错误响应

LLMPool 的 OpenAI 兼容接口与 Anthropic 兼容接口使用各自协议的错误格式。应用应先判断 HTTP 状态码，再读取协议对应的结构化错误字段。

错误消息用于帮助人阅读，不是稳定的程序解析契约。不要通过匹配 message 文本决定重试或业务分支。

OpenAI 兼容格式

OpenAI 兼容接口的标准化错误返回 error 对象：

{
  "error": {
    "message": "The requested model was not found.",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found"
  }
}

程序处理时优先使用 HTTP 状态码与 error.code，error.type 用于区分认证、请求、限流和服务端错误等大类。

Anthropic 兼容格式

Anthropic 兼容接口的标准化错误返回顶层 type: "error"：

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "The requested model was not found."
  }
}

Anthropic 客户端应主要根据 HTTP 状态码与 error.type 处理错误。

字段由谁定义

结论： 本文列出的常见结构化错误码和类型是 LLMPool 的客户端契约；message 不是稳定契约，即使当前文案由 LLMPool 返回，也可能在不改变错误语义的情况下调整。

非 2xx 业务响应例外

少数兼容上游会错误地为结构合法的业务响应附加非 2xx 状态。LLMPool 在确认响应结构与目标端点匹配后，可能保留该 HTTP 状态并返回业务对象，而不是替换为标准错误 envelope：

• Chat Completions 和 Responses 可能返回结构合法的 OpenAI 业务对象。
• Anthropic 非流式 Messages、Files 和 Message Batches 可能返回结构合法的 Anthropic 业务对象。
• Responses 对象可能带 status: "failed"，同时保留正常的 Response 对象结构和用量信息。

该例外不适用于无法识别的响应正文或流式握手失败，这些情况仍进入标准化错误路径。使用原始 HTTP 的客户端在处理非 2xx 时，应先确认正文是否为目标端点的业务对象，再尝试读取错误 envelope；不同 SDK 对非 2xx 业务对象的处理方式可能不同。

常见 HTTP 状态码

详细原因和解决步骤见故障排除。

流式错误

流式请求可能在 HTTP 200 和响应头已经发送后发生错误。客户端必须继续解析 SSE 事件，不能只检查最初的 HTTP 状态码。

Chat Completions

Chat Completions 在 SSE data 中使用 OpenAI 错误对象：

{
  "error": {
    "message": "Upstream stream interrupted.",
    "type": "server_error",
    "param": null,
    "code": "stream_error"
  }
}

Responses API

Responses API 使用顶层错误事件，并包含递增的 sequence_number：

{
  "type": "error",
  "code": "stream_error",
  "message": "Upstream stream interrupted.",
  "param": null,
  "sequence_number": 7
}

Responses API 还可能收到合法的 response.failed 终态：

{
  "type": "response.failed",
  "sequence_number": 7,
  "response": {
    "id": "resp_123",
    "object": "response",
    "status": "failed",
    "error": {
      "code": "server_error",
      "message": "The response failed."
    }
  }
}

response.failed 是 Responses 协议中的业务终态，不是 LLMPool 合成的 stream_error。LLMPool 会转发该事件并结束流，不会再追加一个合成错误事件。客户端必须同时处理 type: "error" 和 type: "response.failed"。

Anthropic Messages

Anthropic Messages 使用 SSE event: error：

{
  "type": "error",
  "error": {
    "type": "api_error",
    "message": "Upstream stream interrupted."
  }
}

收到流式错误或失败终态后应结束当前流，不要把已经接收的内容当作完整响应。是否重新提交取决于请求是否可以安全重试。

重试原则

• 400、401、402、403、404、405、413 和 422 通常需要先修正请求或账户状态，不应原样自动重试。
• 429 rate_limit_exceeded、429 rate_limited、502 upstream_unavailable、503 service_unavailable、504 upstream_timeout 和 529 overloaded_error 可以使用带随机抖动的指数退避。
• 502 upstream_configuration_error 和 400/500 meter_price_rules_error 属于平台配置问题，原样自动重试通常无效。
• 500 internal_error 或 Anthropic 500 api_error 可以进行少量退避重试；如果持续出现，应停止重试并联系支持。Anthropic api_error 也可能代表上游配置错误，不能仅凭该类型确定根因。
• 优先遵循响应中的 Retry-After Header。
• 创建资源、Batch 等非幂等操作在重试前应确认首次请求是否已经成功，避免重复创建。
• 为所有自动重试设置最大次数和总超时时间，避免重试风暴。

LLMPool 不会在标准化错误中返回上游原始响应、上游凭证、内部模型名称、API Base 或代理地址。联系支持时也不要发送完整 API 密钥、请求正文或文件内容。

Files、Batches、Responses 等特殊接口的处理建议见故障排除。