上游错误码各说各话：大模型API聚合层怎么把报错翻译成同一套语言

同时接入两三个模型上游之后，很多团队最先遇到的麻烦不是效果，而是报错。同一段调用代码，昨天跑得好好的，换一个上游就返回一个从没见过的错误结构，日志里堆着几种格式的响应体，监控告警规则写了一条又一条，还是盖不全。错误码不统一这件事，看起来只是字段差异，实际会一路传导到重试策略、告警阈值和故障定位效率上。

先看最表层的问题：HTTP 状态码语义漂移。虽然 401、429、500 这些数字是通用的，但不同厂商往里塞的含义并不一致。有的把限流老老实实写成 429，并在响应头里带上重试等待时间；有的则返回 200，把配额不足包装成响应体里的一个业务码；还有的把鉴权失败统一写成 403，让人一时分不清是密钥错了还是权限不够。

再往里一层，错误体的结构差异更大。一类是 OpenAI 风格的嵌套结构，错误信息放在 error 对象里，含 message、type、code 几个字段，层级清晰；另一类是平铺结构，直接给一个 code 加一句 message；还有些上游只返回一句中文描述，既不区分参数错误和上下文超长，也不标明是否可重试。对写客户端逻辑的人来说，这意味着每接一家就要写一套解析分支。

这些差异堆在一起，会直接抬高日常运维成本。监控系统很难用一套规则识别所有上游的失败；重试逻辑往往写成针对某一家错误码的白名单，一旦切换上游就失效；更麻烦的是排障时，值班同学要先判断这个报错是哪家返回的、字段含义是什么，才能开始找原因，大量时间消耗在格式识别而不是问题定位上。

聚合层能做的事，正是把这层差异挡在网关内部。核心机制是一张错误映射表：输入是上游的原始响应，包括 HTTP 状态码、响应体里的业务码、错误文本的关键特征，输出是一套统一的错误码体系。所有从网关流出的失败响应，都按同一套字段结构返回，客户端只需要解析一种格式。

归一化通常分几个维度同时做。第一是状态码归一，把语义相近的上游状态映射到同一个统一码；第二是错误归类分层，明确区分是调用方参数问题、上游服务问题，还是网关自身问题；第三是消息保留，统一码之外仍保留上游原始错误文本，便于追溯真实原因；第四是重试语义标记，在归一后的错误里直接说明是否可重试、建议退避多久，让客户端不用猜。

限流错误是这套机制里最能体现价值的部分。429 几乎是所有上游都会出现的错误，但配额窗口的口径五花八门，有的是每分钟请求数，有的是每分钟令牌数，有的按并发连接算，返回的重试提示有的在响应头、有的只在文本里。聚合层把这些差异吸收掉之后，对外统一给出可重试标记和退避建议，客户端才能只写一份通用的等待与重试逻辑。

排查方法也可以借助归一后的结构固定下来，比较实用的做法是三段式。先用统一错误码判断问题大类，是参数、鉴权、限流还是上游异常；再调取网关记录的原始响应，看上游到底说了什么；最后用请求 ID 把网关日志和上游调用串起来，确认是单次抖动还是持续性问题。三段各司其职，比在混合格式里逐条猜要快得多。

在这类场景下，快米兔 API 中转的处理方式有一定参考价值。它兼容 OpenAI 协议，把不同上游返回的错误统一翻译成一套标准错误结构，调用方拿到的字段形态基本保持一致；同时保留原始错误信息，排障时能够向上追溯。对于习惯 OpenAI SDK 的团队来说，切换模型主要改路由配置，错误处理代码基本不用重写。

成本侧同样需要关注错误码带来的口径问题。失败请求是否计费、上游返回部分结果时怎么结算，不同上游的规则并不一致。快米兔 API 中转采用按量计费，注册赠送 5 元测试金，团队可以用很小的成本把各家上游的报错行为、限流触发点跑一遍，验证自己的重试和降级逻辑是否成立，具体计费细则以官方说明为准。

从选型角度看，多模型接入时值得重点确认几件事：错误归一是否覆盖了常见状态码与业务码、是否保留原始错误便于溯源、是否标记可重试性、是否提供请求 ID 串联链路。这些能力不会直接体现在模型效果上，却决定了后续运维是写一份逻辑还是写十份适配。

错误码不统一是聚合层天然要解决的问题，也是衡量一个 API 中转服务是否成熟的重要侧面。把上游差异翻译成同一套语言，让客户端只面对一种错误结构、一份重试逻辑，多模型接入的复杂度才会真正降下来，团队也才能把精力放回业务本身。