OpenAI 兼容客户端报错时：聚合站错误响应与各厂商原始错误的对照表

为什么需要区分错误来源

用 OpenAI 兼容客户端（openai SDK、LangChain、各类第三方工具）打聚合站时，返回的仍是 OpenAI 风格的 error 对象。但同一条 401 或 429，可能来自聚合站网关，也可能来自上游厂商。两类问题的处理路径完全不同：前者去查自己的 key 和余额，后者要改请求体或换模型。误判会浪费大量时间。

判断错误来源的三个信号

1. 看响应体结构

聚合站自身错误通常返回规整的 OpenAI 格式：

• error.type 为聚合站自定义的类型名
• error.code 为稳定的机器可读字符串
• error.message 是聚合站自己的措辞，会提到 key、余额、模型路由等概念

上游透传的错误往往保留厂商自己的字段风格，比如 error.type 出现厂商特有命名、message 里带厂商名，或直接是厂商原样的 JSON 嵌套。

2. 看响应头

聚合站一般会附上请求 ID、路由到的上游模型、上游返回状态等头信息。上游错误里通常会有一个上游请求 ID，聚合站错误里则是聚合站自己的请求 ID（或两者都有）。排查时优先把请求 ID 记录下来，它是定位问题的唯一凭据。

3. 看可复现性

• 换一个模型就正常 → 大概率是上游或模型侧问题
• 换一个 key 就正常 → 大概率是聚合站鉴权或配额问题
• 同一请求稳定复现 → 请求体校验或内容策略
• 间歇出现 → 限流或上游抖动

常见状态码的对照与排查

401 / 403 鉴权类

聚合站侧：key 无效、被撤销、格式不对（少了前缀、复制时带了空格换行）、请求头没按 Authorization: Bearer <key> 传。

上游侧：较少见，通常是聚合站转发时上游拒绝了聚合站自己的凭据，属于平台内部问题。

排查动作：用最小请求（一个短 prompt）单独测试 key；确认环境变量没被其他配置覆盖；确认 SDK 的 base_url 指向聚合站而不是官方。

402 / 余额类

聚合站侧：账户余额不足。聚合站按官方价乘以固定系数扣费，余额耗尽会直接拒绝，不会转发上游。

上游侧：聚合站不会把上游的欠费错误暴露给你。

排查动作：查账户余额与近期扣费记录；确认充值已到账（链上充值需要确认数）。

404 / 模型不存在

聚合站侧：模型名不在聚合站支持的清单里，或写法与清单不一致（大小写、版本后缀、厂商前缀）。

上游侧：模型名正确但上游临时下线该版本。

排查动作：用聚合站的模型清单接口拉一次列表，和请求里的字符串逐字符比对；不要凭记忆写模型名。

400 / 422 请求体类

上游侧居多：参数不被该模型支持（如某些模型不接受 temperature 的极端值、response_format、工具调用字段）、消息角色顺序不合法、图片或文件字段格式不对。

聚合站侧：请求体不是合法 JSON、超出体积上限、缺少必填字段。

排查动作：把请求体降到最小可用集（model + messages）逐项加回参数；注意 OpenAI 兼容不等于完全等价，不同厂商对同一字段的容忍度不同。

429 限流

聚合站侧：你的账户级速率或并发限制。

上游侧：聚合站转发时上游对该模型限流，聚合站把上游的 429 透传。

排查动作：看错误体里是否带 retry-after；降低并发或请求频率后重试；换一个模型验证是账户级还是模型级。

5xx 服务端错误

上游侧居多：厂商过载、区域故障、超时。聚合站侧也会有网关超时。

排查动作：带退避重试；记录请求 ID；同一模型连续 5xx 时切换备用模型；把请求 ID 提供给聚合站支持。

上下文超限

这个错误最容易被误读。上游通常返回 400 并说明 token 超限，但不同厂商措辞差异很大，有些只说“输入过长”。聚合站可能不改写这条消息。

排查动作：先估算输入长度（含系统提示、历史消息、工具 schema）；确认不是把整段长文档塞进单次请求；改用分块或摘要策略。

内容策略拦截

上游侧：厂商的安全过滤拒绝生成或拒绝输入。这类错误文案因厂商而异，可能表现为 400 或 200 但内容为空。

排查动作：检查是否触发了厂商侧过滤；换模型对比是否仍被拦截；不要把它当成网络错误反复重试。

一套可复用的排查流程

1. 记录完整响应体、状态码、请求 ID、路由到的上游模型。
2. 用最小请求复现：只保留 model 和一条短 user 消息。
3. 最小请求也失败 → 查 key、余额、模型名，属聚合站侧。
4. 最小请求成功 → 逐步加回参数，定位是哪个字段或哪段内容触发，属请求体或上游侧。
5. 换模型对比：只有某个模型失败，问题在该上游；全部失败，问题在聚合站或账户。
6. 仍不确定时，把请求 ID 和响应体一并提交给聚合站支持，不要只发一句“报错了”。

客户端配置上的几个易错点

• base_url 要包含聚合站要求的路径前缀，缺一段会得到 404，看起来像模型不存在。
• 部分 SDK 默认会读取官方环境变量，本地存在旧变量时会覆盖你显式传入的配置。
• 流式请求的错误可能在流开始后才返回，客户端要能解析流内的 error 事件，否则只会看到空响应或连接中断。
• 重试逻辑要区分可重试（429、5xx、超时）与不可重试（400、401、404），否则会把参数错误重试成限流。

小结

区分错误来源的关键不是背状态码，而是建立“最小请求 + 换模型 + 换 key”的对照实验习惯，并保留请求 ID。聚合站在其中扮演的是转发与鉴权层，理解这一点，就能快速判断该改代码、改配置，还是等上游恢复。