同一个错，六家不一样：Claude、GPT、Qwen 的报错风格差异对照

为什么需要错误归一化

当你的应用同时接入多个 LLM 提供商（如 Claude、GPT、DeepSeek、Qwen、GLM、Kimi）时，每个上游的 API 返回的错误结构、状态码语义甚至错误描述措辞都可能不同。如果直接将这些原始错误抛给前端或业务逻辑，会导致处理分支爆炸、日志难以聚合、用户体验不一致。

错误归一化的目标：定义一套内部统一的错误类型和字段，将各上游的错误映射到这套标准上。

常见上游的报错风格对比

不同提供商的错误响应通常包含 HTTP 状态码和 JSON 错误体，但字段命名和结构各有特点：

• OpenAI 风格：错误体通常包裹在 error 对象中，包含 message、type、param、code。例如参数错误时 type 为 invalidrequesterror，权限问题为 insufficientquota 或 authenticationerror。
• Anthropic 风格：错误体为 error 对象，包含 type 和 message。type 常见值有 invalidrequesterror、authenticationerror、permissionerror、notfounderror、ratelimiterror、apierror、overloadederror。
• 国内模型（如 Qwen、GLM、DeepSeek）：多兼容 OpenAI 格式，但细节可能有差异，比如 code 字段可能为数字或字符串，message 可能包含中文提示。

尽管风格不一，但核心错误类别是相通的：认证失败、权限不足、请求参数错误、资源不存在、速率限制、服务端内部错误、超时等。

构建归一化错误映射表

1. 定义内部错误分类

首先设计一套与提供商无关的错误枚举，例如：

• AUTHENTICATION_FAILED
• PERMISSION_DENIED
• INVALID_REQUEST
• NOT_FOUND
• RATE_LIMITED
• PROVIDERINTERNALERROR
• TIMEOUT
• UNKNOWN

每个分类可附带原始错误信息、上游名称、请求 ID 等元数据，便于排查。

2. 收集各上游的错误样本

通过实际调用或文档，收集每个提供商在各种错误场景下的响应。不要依赖猜测，最好用测试用例触发错误并记录完整的 HTTP 状态码和响应体。

3. 编写映射函数

为每个提供商实现一个映射函数，输入原始错误响应，输出内部错误分类。映射逻辑可以基于状态码、错误体中的 type、code 或 message 关键词。

示例思路（伪代码）：

function mapOpenAIError(status, body) {
  if (status === 401) return AUTHENTICATION_FAILED;
  if (status === 403) return PERMISSION_DENIED;
  if (status === 404) return NOT_FOUND;
  if (status === 429) return RATE_LIMITED;
  if (status >= 500) return PROVIDER_INTERNAL_ERROR;
  if (body.error?.type === 'invalid_request_error') return INVALID_REQUEST;
  return UNKNOWN;
}

对于 Anthropic，可类似地根据 error.type 映射：

• authenticationerror → AUTHENTICATIONFAILED
• permissionerror → PERMISSIONDENIED
• invalidrequesterror → INVALID_REQUEST
• notfounderror → NOT_FOUND
• ratelimiterror → RATE_LIMITED
• apierror 或 overloadederror → PROVIDERINTERNALERROR

国内模型若兼容 OpenAI，可直接复用 OpenAI 映射，但需处理可能的差异（如状态码使用 200 但错误在 body 中）。

4. 处理边界情况

• 网络超时或连接失败：归类为 TIMEOUT，并记录上游名称。
• 流式响应中的错误：某些提供商会在 SSE 流中发送错误事件，需要单独解析。
• 非 JSON 响应：如 HTML 错误页，应视为 PROVIDERINTERNALERROR 并记录原始内容。

在聚合层统一处理

如果你使用 LLM API 聚合服务（例如支持一个 API key 调用多个模型的中转站），通常聚合层已经做了部分错误归一化。但为了应用层的灵活性，建议仍然在客户端或网关层实现自己的映射逻辑，以便：

• 统一重试策略（如仅对 RATELIMITED 和 PROVIDERINTERNAL_ERROR 重试）
• 统一用户提示（如认证失败时引导检查 API key）
• 统一监控告警（按内部错误分类统计）

测试与维护

错误映射表需要随上游 API 变化而更新。建议：

• 为每个提供商编写集成测试，模拟错误响应，验证映射结果。
• 定期检查上游文档的变更日志。
• 在日志中记录原始错误，以便发现未映射的新错误类型。

通过系统化的错误归一化，多模型应用可以更稳健地处理各种异常，提升开发效率和用户体验。