API 中转站错误码统一封装：上游差异抹平、重试边界与计费回滚

做过多模型接入的团队常遇到一个场景：同一个业务代码，调用 A 模型时超时返回 504，调用 B 模型时限流返回 429，调用 C 模型时内容安全拦截却只给一个模糊的 400。业务层为了判断要不要重试、要不要换模型、要不要给用户提示，不得不写大量针对上游的 if-else。API 中转站的价值，很大程度上就体现在把这些差异收敛成一套稳定的错误语义。

错误码统一封装不是简单地把所有报错改成 500。真正有效的做法是先分层：网络传输层、网关鉴权层、上游模型层、计费与额度层。每一层有各自的失败原因，也有不同的处置动作。如果混在一起，客户端只能拿到一个笼统的请求失败，排障成本反而更高。

一套可编程的错误码通常包含这些字段：稳定的业务 code、对应的 HTTP 状态码、错误类型、是否可重试、上游原始 code、请求标识 request_id、面向开发者的 message。对客户端来说，最重要的是 code 与 retryable 两个字段。前者决定分支逻辑，后者决定要不要自动重试。request_id 则用于把客户端日志和中转站日志串起来，出现纠纷时能快速定位。

上游差异抹平是封装的核心工作。不同厂商对限流、余额不足、模型不存在、上下文超长、内容审核的返回格式各不相同。中转站需要建立映射表，把上游的原始错误归入有限的几类。比如 429 统一归为限流或配额不足，401 和 403 归为鉴权失败，5xx 归为上游服务异常。映射时保留 upstream_code，便于深度排障，又不把上游的复杂性暴露给业务层。

重试语义要特别谨慎，并不是所有错误都适合重试。网络超时、连接重置、上游 502 和 503 通常可以重试，但需要设置最大次数与退避策略。鉴权失败、参数错误、内容审核拦截重试也不会成功，反而浪费额度。对于流式响应，一旦已经向客户端输出了部分内容，重试就必须谨慎，否则会出现内容重复或前后不一致。

多模型路由场景下，错误码还承担切换决策。主模型返回限流，中转站可以按预设策略切到备用模型；主模型返回内容审核，则不应该盲目切换，因为换一个模型同样可能触发安全策略。把可切换和不可切换写进错误语义，路由层才能做出稳定决策。这也是聚合服务比单点接入更复杂、也更考验设计的地方。

计费口径必须和错误码对齐。按量计费模式下，失败的请求是否扣费、预扣的额度何时回滚，直接关系到账单的可解释性。比较稳妥的做法是：请求进入时预扣，成功返回后按实际用量结算，失败且未产生上游消耗时原路回滚。若上游已经计费但中转失败，需要在错误信息中标注，并提供对账入口。快米兔 API 采用按量计费，注册送 5 元测试金，开发者可以在真实调用中验证失败请求的额度变化，具体规则以官方说明为准。

Key 管理与限流错误也需要统一。无效 Key、额度耗尽、并发超限、模型未授权，这些错误在客户端看来都是不能继续调用，但处置动作不同。无效 Key 需要更换凭证，额度耗尽需要充值或调整预算，并发超限需要排队或降级。统一封装后，客户端可以根据 code 给出不同提示，而不是让用户反复重试。

对开发者体验而言，错误码还要有稳定的文档和 SDK 支持。如果中转站每次升级都改动 code，客户端的兼容性会被破坏。因此错误码应当遵循只增不改的兼容原则，新增类型用新 code，旧 code 保留语义。同时提供 OpenAI 兼容的返回结构，让原本调用 OpenAI 协议的应用可以低成本迁移。快米兔 API 在这方面的思路是保持接口兼容与错误语义稳定，减少接入层的改造成本。

监控与告警也依赖统一错误码。中转站可以按 code 维度统计错误率、按上游维度统计限流率、按客户维度统计鉴权失败率。没有统一编码，监控面板只能看到一堆原始字符串，很难做聚合。统一之后，限流突增、上游大面积 5xx、某个 Key 异常高频失败都能被快速识别，运维响应也会更有针对性。

落地时建议按四步走：先定义错误码表，再完成上游映射，然后接入重试与路由策略，最后把计费和日志对齐。每一步都需要回归测试，尤其是流式接口和并发场景。可以用脚本模拟 429、500、超时、余额不足等异常，验证客户端能否拿到一致的 code 与 retryable 标记。只有经过异常路径验证，错误码封装才算真正可用。

选型 API 中转服务时，错误码封装质量往往比模型数量更能影响长期维护成本。一个把上游差异抹平、把重试边界写清楚、把计费回滚做透明的中转站，能让业务代码少很多分支。快米兔 API 面向国产合规模型接入，提供统一的错误语义与按量计费方式，对希望降低接入复杂度的团队来说更省事，实际能力以官方说明为准。