作者注：本文按错误码讲解 AI API 报 429、401、500 时的原因和处理方式，说明哪些错误该重试、哪些该修配置，以及指数退避、多模型降级和熔断各自适用的范围。
线上调用大模型时，凌晨告警群里出现一串 429、401、500，是很多开发者都经历过的场景。常见的应对是给所有失败请求加一层重试，但这样做往往让情况更糟。本文按错误码分类讲解 AI API 报 429、401、500 时的判断方法与容错设计，帮你把“盲目重试”换成“分类处理”。
这不是一篇 HTTP 状态码科普，而是面向线上运维的实践指南。内容包括每类错误的典型原因、能不能重试、应用层怎么写处理逻辑，以及网关层和应用层容错怎么分工。
核心价值：读完本文，你能在几分钟内判断一个报错该重试、该降级还是该立即修配置，并清楚指数退避、多模型降级和熔断各自适合什么场景。
AI API 报 429、401、500 的核心要点
处理 AI API 报错，第一步是分类，重试放在后面。不同错误码代表的问题性质不同，有的等一会儿就能自愈，有的不管重试多少次都会失败。下表先给出三类错误的整体判断。
| 错误类别 | 典型状态码 | 问题本质 | 能否重试 | 核心处理方式 |
|---|---|---|---|---|
| 限流类 | 429 | 请求太快或额度耗尽 | 视原因而定 | 读取 Retry-After，指数退避，区分限流与额度不足 |
| 认证类 | 401、403 | 密钥无效、权限不足 | 不能 | 立即停止重试，告警并修正配置 |
| 服务端类 | 500、502、503、504 | 上游故障或过载 | 可以，有上限 | 有限次退避重试，持续失败时降级或熔断 |
| 请求类 | 400、404、413、422 | 参数、模型名、长度有误 | 不能 | 记录请求体，修正参数后再发 |
可以看出，能不能重试取决于错误是暂时的还是确定的。暂时性错误（限流、上游抖动）重试有意义。确定性错误（密钥错、参数错）重试只会浪费额度、拖慢响应，还可能触发更严格的限流。
AI API 错误码判断决策表
实际排查时，光看状态码还不够，还要结合响应体里的错误类型字段和响应头。下表是一份可以直接用于设计应用层逻辑的决策表。
| 观察到的信号 | 可能原因 | 推荐动作 | 是否计入熔断统计 |
|---|---|---|---|
429 且带 Retry-After 头 |
速率限制 | 按头部给出的时间等待后重试 | 否 |
| 429 且错误体提示额度/余额不足 | 账户额度耗尽 | 不重试，告警充值或切换账户 | 否 |
| 401 | 密钥错误、过期或格式不对 | 不重试，检查密钥与环境变量 | 否 |
| 403 | 密钥无权访问该模型或区域 | 不重试，检查权限与模型开通情况 | 否 |
| 500 / 502 | 上游内部错误、网关转发失败 | 退避重试 2-3 次 | 是 |
| 503 | 服务过载或维护 | 退避重试，失败后降级 | 是 |
| 504 或客户端超时 | 生成太长、上游响应慢 | 视幂等性决定是否重试，考虑调大超时 | 是 |
表里最容易被忽略的是 429 的两种含义。部分服务商在额度耗尽时也返回 429，但错误体里的类型字段和普通限流不同。如果应用层只看状态码，就会对一个“余额不足”的请求无限退避重试，日志里全是 429，却始终不会恢复。
429 限流错误重点详解
429 的核心原因是单位时间内请求数或 token 数超过了限制。大模型 API 的限流通常有多个维度：每分钟请求数、每分钟 token 数，有的还有并发数限制。所以即使请求数不多，一次塞进超长上下文也可能触发 429。
应用层处理 429 有三条原则。第一，优先遵守 Retry-After 或类似的重置时间头，不要自己猜等待时间。第二，在没有头部提示时使用带随机抖动的指数退避，避免大量客户端同时醒来再次打满限额。第三，从源头控流，用令牌桶或队列限制并发，比事后重试更有效。
401 认证错误重点详解
401 是最不该重试的错误。它几乎总是由配置问题引起，常见情况有：密钥复制时多了空格或换行，环境变量在容器里没有正确注入，测试环境的密钥被带到了生产，密钥已被轮换或吊销，或者使用了错误的鉴权头格式。
在 OpenAI 兼容接口下，还有一个高频原因是 base_url 和密钥不匹配，比如用 A 平台的密钥请求 B 平台的地址。因此 401 出现时，应用层应当立即停止重试、触发高优先级告警，并在日志中记录密钥前几位与请求地址，方便快速定位，但不要记录完整密钥。
500 服务端错误重点详解
500 系列错误说明问题在服务端或链路上，可能是上游模型服务内部异常、负载过高，也可能是中间网关转发失败。这类错误通常是暂时性的，适合有限次数的重试。但如果持续出现，就说明上游进入了不健康状态，这时继续重试只会让请求排队、线程被占满，应该转向降级或熔断。
还要注意 504 和客户端超时。大模型生成长文本本身就慢，如果超时时间设得太短，会把正常的慢请求误判为失败，然后重试，这会产生重复计费，在流式输出中断时还会让前端收到截断的内容。
AI API 重试、降级与熔断快速上手
分好类之后，就要把处理逻辑落到代码里。按照补充要求，本节不贴代码块，而是用参数清单和步骤说明讲清每种机制的实现要点，你可以照着在任意语言里实现。
指数退避重试的实现要点
指数退避的思路是：每次重试的等待时间按倍数增长，再叠加随机抖动。实现时可以按下面的步骤组织逻辑：
- 定义可重试的错误集合，例如
429（非额度不足）、500、502、503、504以及网络超时。 - 每次失败后先检查响应头里的
Retry-After，有就按它等待，没有则按退避公式计算等待时间。 - 等待时间公式通常写成“基础间隔 × 2 的重试次数次方”，再加上一个随机抖动值，并设置单次等待上限。
- 设置最大重试次数和总耗时预算，任何一个超限都立即放弃，把错误交给降级逻辑。
- 每次重试都记录日志，包括错误码、重试次数、等待时长和模型名，方便事后分析。
如果你使用官方 SDK，很多 SDK 本身已有 max_retries、timeout 之类的参数。这时要注意不要在外层再包一层同样的重试，否则重试次数会相乘，故障时请求量成倍放大。
下表给出一组常见的起步参数，属于经验值，具体数值应根据你的业务延迟要求和服务商限额调整。
| 参数 | 含义 | 常见起步取值 | 调整依据 |
|---|---|---|---|
max_retries |
最大重试次数 | 2-5 次 | 实时对话取小值，离线批处理可取大值 |
| 基础间隔 | 首次重试等待 | 约 1 秒 | 限流严格的服务可适当放大 |
| 单次等待上限 | 退避时间封顶 | 数十秒级 | 避免单次等待过长拖垮请求 |
| 随机抖动 | 打散重试时间 | 等待时长的一部分随机值 | 并发客户端越多越需要 |
| 总耗时预算 | 一次调用最长耗时 | 按业务 SLA 设定 | 超时后直接降级 |
🚀 快速开始：如果想在测试阶段模拟不同错误码下的重试表现，可以通过 API易 apiyi.com 用统一的 OpenAI 兼容接口接入多个模型，在同一套重试逻辑下观察不同模型的响应和报错情况，减少为每家服务商单独适配的工作量。
多模型降级的设计方法
重试解决的是“同一个模型暂时不可用”，降级解决的是“这个模型短时间内恢复不了”。多模型降级就是预先配置一条备用链路：主模型连续失败后，按顺序切换到备用模型，保证业务能继续响应，代价是可能牺牲一部分质量或增加一部分成本。
设计降级链时要考虑能力是否等价。如果主模型依赖函数调用、结构化输出或长上下文，备用模型也必须支持这些特性，否则降级后会出现新的 400 错误或输出格式解析失败。下表给出一种按场景设计降级链的参考思路。
| 业务场景 | 主模型定位 | 一级备用 | 二级兜底 | 可用平台 |
|---|---|---|---|---|
| 在线客服对话 | 高质量通用模型 | 同级别的其他厂商模型 | 轻量快速模型 + 简化回复 | API易 apiyi.com、各家官方 API |
| 代码生成与审查 | 编程能力强的旗舰模型 | 另一家旗舰模型 | 返回“稍后重试”提示 | API易 apiyi.com、各家官方 API |
| 批量内容处理 | 性价比模型 | 同价位其他模型 | 写入队列延后处理 | API易 apiyi.com、各家官方 API |
| 结构化信息抽取 | 支持 JSON 输出的模型 | 同样支持结构化输出的模型 | 规则引擎兜底 | API易 apiyi.com、各家官方 API |
降级时有几个细节需要处理好：
- 提示词适配：不同模型对系统提示词的敏感度不同，备用模型最好有经过验证的独立提示词版本。
- 上下文长度：切换前检查消息长度是否超过备用模型的上下文窗口，必要时先截断历史。
- 结果标记：在日志和监控里标记“本次响应来自降级模型”，便于评估降级对质量的影响。
- 不要降级认证错误：401 说明配置有问题，切换模型只会掩盖问题，应该直接告警。
熔断器的工作原理与使用边界
熔断器用来防止一个持续故障的依赖拖垮整个系统。它通常有三种状态：关闭时请求正常放行，同时统计失败率；失败率或连续失败次数超过阈值后进入打开状态，此时直接拒绝请求或走降级，不再访问故障上游；经过一段冷却时间后进入半开状态，放少量试探请求，成功则恢复关闭，失败则重新打开。
熔断的关键是只统计能代表上游健康度的错误。5xx 和超时应该计入失败率，而 401、400 这类客户端错误不应计入，否则一个配置错误就会让熔断器打开，所有正常请求都被拒绝。按额度不足返回的 429 也不应计入，它反映的是账户状态，不是服务健康度。
熔断也不是越多越好。对于调用量很低的内部工具，失败率统计样本太少，熔断器容易误判，这时用简单的重试加降级就够了。熔断更适合高并发的线上服务，它能在上游大面积故障时快速止损，避免线程池和连接池被慢请求占满。
网关层与应用层容错的分工
越来越多团队通过 API 网关或聚合平台调用大模型。这时常见的疑问是：网关已经有自动降级，应用层还要不要做重试和熔断？答案是要做，但分工不同。网关擅长处理“上游渠道”层面的问题，应用层更了解“业务语义”层面的问题，两边各管一段。
| 容错职责 | 网关层更适合 | 应用层更适合 |
|---|---|---|
| 渠道故障切换 | 同一模型多渠道切换、负载均衡 | 无需重复实现 |
| 跨模型降级 | 可提供模型路由能力 | 决定业务是否接受质量降级、是否需要换提示词 |
| 重试 | 渠道级的快速重试 | 业务级重试预算、与用户超时体验协调 |
| 熔断 | 针对上游渠道的健康检查 | 针对整个网关不可达的熔断与兜底 |
| 认证与额度错误 | 返回明确的错误类型 | 告警、阻断重试、通知人工处理 |
| 监控 | 渠道层面的成功率与延迟 | 业务层面的成功率、降级比例、用户影响 |
以 API易 为例，其业务介绍中提到了自动降级、负载均衡和实时监控等稳定性能力，这类能力适合承担渠道层面的故障切换，应用层可以把精力放在业务兜底上。不过，网关的降级触发条件、返回的错误码和错误体格式与官方是否完全一致，需要以平台文档和实际测试为准。业务介绍中提到的“不限并发”也不等于永远不会出现 429，上游模型本身的限制依然存在。稳妥的做法是：应用层始终保留对 429、5xx 的处理逻辑，并在网关整体不可达时有自己的兜底方案。
🎯 技术建议：接入网关后，建议先在测试环境故意触发几类错误，比如使用错误密钥、请求不存在的模型名、发送超长上下文，记录 API易 apiyi.com 实际返回的状态码与错误体字段，再据此调整应用层的错误分类规则，而不是照搬官方文档的错误格式。
常见问题 FAQ
Q1：AI API 报 429 和报 500 有什么本质区别？
429 表示你的请求超出了限额，问题在调用方的节奏或账户额度；500 表示服务端出错，问题在上游。前者应该先降速、遵守等待时间，后者可以有限次重试，持续失败再降级。两者都可能“等一会儿就好”，但处理重点不同。
Q2：为什么 401 错误绝对不要自动重试？
401 是确定性错误，密钥不对时重试一万次结果都一样。自动重试不仅浪费资源，还会掩盖问题，让告警延迟。正确做法是立即中断，检查密钥内容、环境变量注入和请求地址是否匹配。
Q3：429 一直重试都不恢复，可能是什么原因？
最常见的原因是额度或余额耗尽。部分服务商这种情况也返回 429，但错误体中的类型字段与普通限流不同。另一种可能是你的重试没有加随机抖动，大量请求同时重发，持续打满限额。建议先看错误体，再检查重试的时间分布。
Q4：多模型降级会不会影响输出质量？
可能会。降级本质上是用可用性换质量，所以要在业务层面明确哪些场景可以接受降级。建议为备用模型准备独立验证过的提示词，并在监控中统计降级比例。如果降级比例长期偏高，就该检查主模型的配额和稳定性了。
Q5：如何低成本测试不同模型的降级链路？
可以借助支持多模型统一接口的平台搭建测试环境。比如通过 API易 apiyi.com 用同一套 OpenAI 兼容调用方式切换不同厂商的模型，只需修改模型名，就能验证主备模型在相同提示词下的输出差异和报错表现，适合在上线前跑一遍降级演练。
Q6：使用了带自动降级的网关，应用层还需要熔断吗？
需要。网关的降级解决的是上游渠道问题，但网关本身也可能出现网络不通或整体不可用。应用层的熔断与兜底就是为这种情况准备的。使用 API易 这类网关时，可以把应用层熔断的统计对象设为“网关整体”，而不是单个模型渠道，两层职责就不会重复。
Q7：重试、降级和熔断有哪些已知的副作用？
重试可能产生重复计费，在非幂等场景（如带工具调用的写操作）中可能导致动作重复执行。降级可能带来质量波动和输出格式差异。熔断参数设得过敏会误拒正常请求。因此三者都需要配合监控指标持续调参，不能配置一次就不管。
AI API 错误处理核心要点 Key Takeaways
- 先分类再处理：确定性错误立即修正，暂时性错误才进入重试流程。
- 429 要看错误体：区分速率限制和额度耗尽，后者重试没有意义。
- 401 永不重试：直接告警，重点排查密钥、环境变量和接口地址是否匹配。
- 重试要有上限：指数退避加随机抖动，设置次数和总耗时双重预算。
- 降级要能力对齐：备用模型需支持相同特性，并配套独立提示词。
- 熔断只算服务端错误：5xx 和超时计入失败率，客户端错误不计入。
- 网关与应用分工：可借助 API易 apiyi.com 处理渠道层容错，应用层负责业务兜底。
总结
AI API 报 429、401、500 时，最重要的是放弃“统一重试”的习惯，改为按错误性质分别处理：
- 限流类错误：遵守
Retry-After，用指数退避加抖动重试，同时从源头控制并发和 token 用量。 - 认证与请求类错误：立即中断、告警、修配置，绝不自动重试，也不要用降级掩盖。
- 服务端错误：有限次重试，持续失败时切换备用模型，高并发场景配合熔断器快速止损。
- 网关与应用分层：网关处理渠道切换与负载，应用层掌握业务语义、重试预算和最终兜底。
建议先把本文的决策表整理成团队内部的错误处理规范，再按规范做一次故障演练，确认每类错误都能走到预期的分支。
如果你正在规划多模型的降级链路，可以通过 API易 apiyi.com 在统一接口下对比多个模型的表现和报错行为，先在测试环境验证容错策略，再上线到生产。
📚 参考资料
- Ofox.ai Blog – AI API Error Handling 主题文章：介绍 429 限流、401 认证、500 服务端错误的处理思路，以及指数退避、多模型降级与熔断器
- 链接：
ofox.ai/blog/page/41/ -
说明：本文选题方向的参考来源，适合对照阅读英文资料
-
Ofox.ai Blog – LLM API Gateway 相关文章：讨论 LLM 网关选型与多服务商故障的背景
- 链接：
ofox.ai/blog/page/40/ -
说明：了解网关层容错能力在多模型架构中的位置
-
API易 文档中心：平台接入说明与使用文档
- 链接：
docs.apiyi.com - 说明：错误码格式、降级行为等细节请以平台文档和实际测试为准
作者：APIYI 技术团队
技术交流：欢迎在 API易 网站首页联系我们交流 AI API 稳定性实践，更多接入资料可查阅 docs.apiyi.com 文档中心
