大模型API返回429怎么办？限流、额度与重试策略排查指南

大模型API返回HTTP 429，通常表示当前请求没有被服务端正常接受，但“请求过多”并不是唯一解释。不同服务商可能把请求频率、并发数、输入输出Token吞吐量、账户额度或配额状态归入429，因此不能看到状态码后直接无限重试。

第一步：先保留完整错误证据

排查时记录HTTP状态码、错误正文中的错误代码和消息、响应头、请求时间、模型标识以及本地生成的请求ID。优先查看服务商文档和控制台中的限流、用量、账单或配额页面，确认该请求使用的项目、组织和密钥是否对应正确账户。不要只根据客户端封装后的“限流”提示下结论。

如果响应包含Retry-After，应优先按其指示等待；如果正文明确提示余额、额度或配额不足，就应先处理账户配置或额度问题。余额不足不应一律当作短暂限流，也不能假设等待一段时间后必然恢复。

区分四类常见原因

• 请求频率：单位时间内请求次数超过限制，常见于循环调用、突发流量或多个实例同时发送。
• 并发限制：同时处于处理中的请求过多，即使平均每分钟请求数不高，也可能触发限制。
• Token吞吐量：输入和输出Token规模较大，单位时间内的Token总量达到限制。长文档批处理尤其需要关注这一点。
• 账户额度或配额：项目、模型、区域或账户存在可用额度、日配额等限制。这类问题通常需要根据控制台或错误正文处理，而非单纯增加重试次数。

设计可靠的重试策略

只对有证据表明可恢复的错误进行重试，并设置最大重试次数、总等待时间和请求超时。没有Retry-After时，可以采用指数退避：每次失败后逐步增加等待时间，并加入随机抖动，避免多个客户端在同一时刻再次冲击服务端。例如等待时间可按“基础等待时间乘以2的重试次数次方”计算，再叠加一个小范围随机值，同时设置单次和总时长上限。这里的具体数值应结合服务商限制和业务时效调整，固定等待时间不能保证成功。

重试前要区分请求是否具有副作用。对于生成文本这类通常可重新提交的请求，应使用稳定的业务请求ID，避免重试造成重复记录；涉及扣费、写入或其他外部操作时，应配合幂等键或先查询结果。若连续达到上限，应把任务标记为待处理或失败并告警，而不是继续循环。

用队列和并发控制减少429

批量处理文档时，不要让所有任务同时调用API。可将任务放入队列，由固定数量的工作进程消费；当429增加时动态降低并发，恢复一段时间后再谨慎提高。对每个模型或项目分别维护并发计数和速率控制，避免多个应用实例各自限流、整体却仍然超出服务商限制。

同时检查是否存在重复调用：客户端超时后未确认结果就立即重发、前端重复提交、消息队列重复投递，都可能放大请求量。缓存确定性结果、合并小请求、限制单次输入长度，并在进入队列前做去重，通常比盲目增加重试更有效。

批量文档处理示例

1. 先读取服务商返回的错误代码和Retry-After，并把原始响应中的密钥等敏感信息过滤后写入日志。
2. 将并发数从较低值开始，按模型或项目单独控制，同时统计请求数、输入输出Token和429比例。
3. 遇到可重试的429时，按Retry-After或带随机抖动的指数退避等待，并限制重试次数。
4. 超过上限后暂停该任务并告警，保留文档ID、请求ID和失败原因，便于人工或后续任务恢复。

最后，应把429排查结果与正常响应、超时、服务端错误区分记录。只有结合错误正文、响应头、控制台指标和本地调用日志，才能判断问题是流量突增、并发配置不当、Token吞吐量过高，还是账户配额已经耗尽。