上游错误码各说各话：模型API报错怎么排查，聚合层如何把错误翻译成统一格式

很多团队第一次同时接入两三家大模型时，都会被日志里的报错形态震住。OpenAI系接口返回的是标准的error对象，某国产模型给你一个顶层code加message，另一个厂商把错误塞进error_code字段，还有的干脆返回HTTP 200，错误藏在响应体里。同一次故障，你在三个平台上要写三套判断逻辑，排查时间被反复拉长。

上游错误码差异的根源在于接口风格并未真正统一。虽然OpenAI的接口格式已经成为事实标准，但各家在错误处理上的自由度依然很大：有的厂商沿用HTTP语义，用状态码区分限流和鉴权失败；有的在业务层定义了一套数字码，HTTP状态码长期固定为200；还有的用嵌套结构承载错误细节，字段名从error到message再到error_code各不相同。对调用方来说，这不是设计优劣问题，而是适配成本问题。

把常见报错按类别拆开看会更清楚。鉴权失败通常表现为401或一套业务码，原因是Key失效、额度耗尽或权限范围不足；限流一般对应429，但有的厂商用200加错误码表达；参数错误多为400，提示往往指向某个字段名；上游服务异常则是5xx，或者流式响应中途断开。同一个问题在不同平台上的表现形态不同，直接导致告警规则难以复用。

排查模型API报错，建议固定一个从外到内的顺序。第一步先看HTTP状态码和响应头，确认是传输层问题还是业务层问题；第二步看响应体的结构，找到错误对象所在层级，不要只盯着状态码；第三步抓取request id或trace id，这是向平台侧追溯的唯一凭据；第四步判断是否发生在流式输出阶段，SSE场景下错误可能出现在第一个分块之后，客户端需要专门处理中途异常；最后用最小请求复现，排除业务参数干扰。

聚合层的第一件事，是建立一张错误映射表。把各家上游的错误码收敛成一组内部枚举，例如鉴权错误、限流、参数非法、额度不足、上游异常、超时、内容安全拦截。这张表是聚合服务最不起眼却最关键的资产，它决定了上层业务能不能用一套逻辑处理所有上游。映射表需要持续维护，因为上游厂商调整错误码并不总是提前公告。

第二件事是输出格式的归一。比较常见的做法是把所有上游错误统一转换成OpenAI风格的error对象，包含message、type、code三个基本字段，同时把上游原始返回完整保留在扩展字段里。这样既能让已经按OpenAI格式写好的代码直接复用，又不会在排障时丢失第一手信息。开发者只需要写一次错误分支，换模型时不用改代码。

第三件事是把可重试与不可重试的错误分开。限流和上游5xx通常适合重试，鉴权失败和参数错误重试多少次都是徒劳。聚合层如果能在归一化阶段就打上可重试标记，调用方就不必自己维护一份庞大的错误码清单。重试还要配合指数退避和随机抖动，并读取上游返回的Retry-After，避免重试风暴把限流问题放大成雪崩。

在多模型路由场景下，错误处理还承担了通道调度的职责。某个上游连续返回5xx或超时，聚合层应当把它标记为不健康并临时摘除，将后续请求切到备用通道；连续限流则要评估是调低权重还是排队等待。这里有两个容易被忽略的细节：切换通道前要确认请求是否幂等，生成类任务重复执行会带来额外成本；流式响应一旦开始输出，中途切换基本不可行，只能在连接建立前做选择。

可观测性是错误归一带来的附加收益。当所有上游的错误都被映射到统一枚举后，监控面板可以按错误类别聚合统计，告警规则写一次就能覆盖全部通道。反过来，如果每个上游各用一套码，你只能为每家单独配置规则，故障复盘时还要人工对齐口径。归一化做得越早，后期接入新模型的边际成本就越低。

快米兔在模型API中转这条线上，把错误结构统一作为基础能力来做，对外返回的错误对象保持一致的字段布局，并保留上游原始信息便于定位问题；计费上采用按量计费，注册送5元测试金，方便团队在正式接入前把限流、鉴权失败、参数错误这些异常分支逐一压测一遍。具体错误码清单与计费口径以官方说明为准。

选型时建议把错误码当成接口契约的一部分来评估。可以重点看三件事：错误结构是否统一、是否保留上游原始错误信息、是否区分可重试与不可重试。把这三条问清楚，再对比接入成本和稳定性，比只看模型数量更有意义。对需要快速上线又要留出切换余地的团队来说，错误处理收敛得更彻底的平台，通常更省事一些。

错误码不统一本身不是故障，但它会放大每一次故障的排查成本。与其在每个业务系统里重复写适配逻辑，不如把翻译归一的职责交给中间层，让上层代码只面对一套语义清晰的错误体系。这是聚合服务真正被低估的价值之一。