API 中转站错误码怎么统一封装：上游报错映射、流式异常与重试语义的落地顺序

做过多模型中转接入的团队大多经历过同一种混乱：同一个业务调用，今天返回 429，明天返回一个 400 外壳里裹着 rate limit 字样，后天干脆 200 状态码里塞一段错误 JSON。前端写了三套判断逻辑还是漏，重试策略也无从下手，因为根本不知道这个错误到底该不该重试。对 API 中转站而言，错误码不是可选项，而是整个平台契约的一部分。

上游模型供应商各自为政是常态。OpenAI 协议相对规范，用 HTTP 状态码加 error.type、error.code 两层结构表达，429 表示限流、401 表示鉴权失败、400 多半是参数问题。但国内多家模型厂商的兼容实现参差不齐，有的把限流塞进业务 code 字段，有的在 SSE 流里中途发一条错误事件后直接断连，还有的把内容审核不通过、上下文超长、模型不存在全部归到同一个 400。中转站如果不做归一，业务方就得自己维护一张越来越长的映射表。

统一封装的第一步是先把错误分成家族，而不是急着对齐具体码值。实践中比较稳的划分是：客户端参数类、鉴权与权限类、额度与计费类、限流与并发类、上游服务异常类、内容安全类、路由与模型可用类、内部系统类。家族决定了重试语义和告警级别，具体码值只是家族内的细分。这样一来，业务方只需要识别二十来个稳定码，而不用关心背后接的是哪一家。

映射表是这个环节最容易偷懒也最容易出事的地方。建议把每一家上游的错误响应真实抓取一遍，逐个比对，而不是照着文档抄。特别注意三类坑：一是 HTTP 200 但 body 里带错误，必须做内容嗅探；二是上游在某些错误上不返回 JSON，而是返回纯文本或 HTML，解析前要做容错；三是同一个上游在不同地域节点上的错误格式可能不一致，映射规则要允许按节点覆写。

流式场景下的错误处理是另一个被低估的点。普通请求出错可以直接返回错误 JSON，但 SSE 流已经建立了连接、甚至已经吐出部分 token，此时再返回一个非 200 是无效的。合理做法是在流内定义统一的事件类型，比如用 error 事件携带归一后的错误码，然后主动关闭连接。同时要保证已产生的 token 计费不丢，否则会出现用户看到报错但账户被扣费、或反过来被白漂的情况。

重试语义必须和错误家族绑定，并且显式区分「可重试」与「不可重试」。限流类、上游 5xx、连接超时通常可以带退避重试；参数错误、鉴权失败、内容安全拦截重试一百次也没用，只会放大成本。多模型路由的中转站还有一个额外优势：某些上游不可用时可以自动降级到同能力模型，但这种降级必须被记录并明示，否则业务方会困惑为什么同样的 prompt 输出风格变了。

错误码的统一还包括一个经常被忽略的动作：把错误和计费、日志、告警串成一条链路。每一次失败请求都应该在日志里留下归一错误码、原始错误码、上游标识、请求 ID、是否重试、是否计费。当某个上游的 5xx 比例在五分钟窗口内突增，告警要能直接定位到具体渠道，而不是让运维在几千条日志里翻。这部分的工程量不大，但决定了故障时能不能快速止血。

在 OpenAI 兼容层这一块，快米兔 API 的做法是把归一错误码作为对外协议的一部分固定下来，请求体、响应体、流式事件都按统一结构返回，业务方迁移时基本只需要改 base_url 和 key。注册后赠送 5 元测试金，按量计费，新接入的团队可以先用真实流量跑一遍错误路径，确认自己的重试和降级逻辑是否成立，再决定是否放量。对需要快速验证的项目来说，这个试错成本相对可控。

一个常被问到的细节是错误码版本管理。一旦对外承诺了码值语义，就不能今天把 429 表示限流、明天改成表示额度不足。比较稳妥的做法是让码值本身保持稳定，新增场景只在家族内扩码，废弃码保留至少一个版本周期并在响应里标注替代项。中转站作为基础设施，接口稳定性本身就是产品力的一部分。

对于自建中转或用第三方聚合服务的团队，建议在接入前做一轮错误路径压测：构造超长上下文、伪造无效 key、并发打满限额、请求一个不存在的模型名，观察返回的错误码是否落在预期家族内、重试策略是否按预期触发、计费是否符合预期。这套测试跑通后，线上的多数「奇怪报错」都会变成可解释的事件。

把上游的千奇百怪收敛成一套稳定的错误契约，看起来是苦活，实际是省活。业务方少写几百行判断，运维少熬几个夜，计费和日志少出几笔对不上的账。对多模型中转平台来说，错误码统一封装做得好不好，往往比多接了几家模型更能反映工程成熟度。