API 限流排障:先辨原因,再决定重试
429 既可能来自请求速率限制,也可能源于余额耗尽或支出上限,不能统一通过重试解决。文章建议结合错误类型、重试响应头和请求标识排查,并强调兼容 OpenAI 的网关未必沿用其错误协议。
AI 深度解读
遇到 HTTP 429,最容易写出的处理是「等一下,再发一次」。但余额耗尽、用量封顶、短时流量过高,都可能表现为同一个状态码,处理方式却不同。重试写得越积极,有时故障反而越难恢复。
Tokenhot 团队这篇文章的核心主张是:先确认服务端拒绝请求的原因,再决定能否重试。它没有提供性能实测,价值在于梳理了 AI API 调用中容易遗漏的边界:网关兼容性、多层重试、流式输出和账户限制。
收到 429,先判断谁拒绝了你
HTTP 429 表示请求触碰了某种限制或策略,但状态码本身没有告诉你具体原因。
作者以直连 OpenAI API 为例,区分了请求速率限制、流量快速增长,以及余额、支出或用量限制。前两类可能需要等待,后几类需要账户操作。429 只能作为排查入口,不能直接作为重试条件。
这里还有一个 AI 应用很常见的误区:接入地址支持 OpenAI-compatible API,就沿用 OpenAI 的错误解析逻辑。
请求格式兼容,不代表错误响应也完全兼容。网关可能修改响应体、移除上游响应头,或者自己施加另一套限额。直连 OpenAI 时使用的错误 code、type 和 x-ratelimit-* 字段,不能直接当成所有兼容接口的契约。应当以接收请求的服务方文档为准。
排查时,先记录请求 ID、时间戳和时区、HTTP 状态、端点归属、模型或路由标识,以及脱敏后的错误码。只有文档说明字段含义时,再用响应体辅助判断;常规日志不应包含 API key、完整 prompt、客户数据或原始响应体。
如果服务方没说明某个错误是否临时可恢复,就停止自动重试,保留现场继续调查。作者也明确反对通过切换账户、新建 key 或改道来绕过限额和服务策略。
Retry-After 是最低等待时间,不是重试许可证
确认错误属于临时限流后,才进入等待策略。
如果端点文档支持 Retry-After,且返回值有效,就至少等待指定时间,再加一点随机延迟。随机延迟也叫抖动(jitter),作用是让同时失败的一批请求错开恢复时间,避免一起重发。
没有这个响应头,或者值无效时,才对已确认的临时错误使用带上限的指数退避:连续失败后逐步拉长等待时间,同时加入随机量。
原文对解析规则讲得很细。按照 RFC 9110,数字形式必须是非负整数秒;nan、inf、-1、1.5 都是无效值,走回退策略。HTTP-date 形式则需要解析日期。原文代码处理了 IMF-fixdate、RFC850 和 asctime 三种日期格式,还校验星期是否匹配。
还有一个容易写反的边界:有效值太大,不能当作无效值处理。原文将去掉前导零后超过 308 位的合法整数表示为 math.inf,让策略判断它超出预算,而不是回退到更短的等待。
例如服务端要求等待的时间超过任务窗口,就延期或失败,不能为了赶上应用超时而提前重试。即便余额错误附带了 Retry-After,也不会因此变成临时错误。
重试预算要算整个调用链
作者提醒,重试经常不只存在于业务代码里。
原文引用的 OpenAI Python SDK 文档说明,符合条件的失败,包括 429,默认重试两次,并可通过 max_retries 配置。具体行为仍需检查实际安装的版本和设置,不能将 Python SDK 的默认值直接套到 Node 客户端。
如果 SDK、任务队列、服务网格和调用方都在重试,一次逻辑操作可能展开成多次 HTTP 请求。解决办法是让一层负责重试,或者把所有层纳入同一份次数与时间预算。
下面这段原文代码展示了预算入口和安全检查:
def bounded_retry(send_once, *, retryable_codes, repeat_is_safe,
max_attempts=4, max_elapsed=45.0, max_server_wait=30.0,
base_delay=0.5, cap_delay=8.0, jitter_seconds=0.5,
sleep=time.sleep, clock=time.monotonic, rng=random.uniform):
"""Return (result, attempts); max_attempts includes the first request.
send_once(timeout_s=...) makes exactly one request and returns status, code,
headers and body. It enforces the supplied remaining-time budget.
"""
if not repeat_is_safe:
raise ValueError("retry requires a documented safe-to-repeat operation")
if max_attempts < 1:
raise ValueError("max_attempts includes the first attempt and must be >= 1")
started = clock()
deadline = started + max_elapsed
重点看 max_attempts=4:它包含首次请求,不是失败后再试四次。其余默认预算是总耗时 45 秒、最大服务端等待 30 秒、基础退避 0.5 秒、退避上限 8 秒、抖动参数 0.5 秒。
但提供的原文代码到 deadline 就结束了,没有实际重试循环。它可以说明接口设计,不能直接作为完整实现使用。
这个接口还依赖两个外部判断:retryable_codes 只能放服务方明确允许重试的临时错误码;repeat_is_safe=True 必须有重复执行安全的依据。适配层的 send_once 需要严格只发一次请求,并把剩余时间 timeout_s 落实到 HTTP 超时配置。
尤其是流式 AI 调用:已经消费部分输出、调用下游工具,或者产生其他副作用后,不能直接从头重放。除非端点提供了覆盖该操作的幂等或结果核对契约,否则重试可能重复执行已经发生的动作。
少制造限流,比增加重试更有效
作者建议先检查共享限额的全部工作量,再考虑提高并发。
同一个组织、项目或路由,可能同时被多个 worker、定时任务和其他服务使用。单个进程看起来并发很低,不代表整体负载很低。
请求频率和 token 总量也要分开看。缩短输入输出、平滑突发流量、在 worker 前增加队列,都可能降低压力。恢复流量时应逐步增加,因为突然放量和持续稳定负载可能触发不同策略。
原文还引用 OpenAI 指南指出,失败请求同样计入每分钟限额。反复重发被拒绝的请求,可能继续消耗容量。
排障记录因此不能只写「429,已重试」。作者建议保留实际客户端版本、各层重试配置、原始格式的 Retry-After、尝试次数、整体截止时间、停止原因、在途请求量,以及输出或副作用是否已经开始。payload 可以记录指纹,不记录内容;向支持渠道提供请求 ID 和脱敏元数据。
我的判断
我认同这篇文章把错误分类放在退避算法前面。实际接入 AI API 时,最难处理的往往不是等待公式,而是接入层是否知道请求为什么失败、之前是否已经执行了一部分。
它也比常见的「捕获 429 后指数退避」多考虑了两件事:整个调用链的预算,以及重复执行的安全性。这些约束对流式响应、工具调用和后台任务尤其有用。
不过,它是一份策略清单,不是经过对照实验验证的最优方案。原文没有吞吐量、恢复时间或不同退避参数的对比,不能把 4 次、45 秒等默认值当成生产推荐值。正文还提到一张错误分类表,但提供的内容里没有表格,具体错误码也没列出来。
与其复制示例参数,我更建议先检查已有 SDK 能否承担所需重试。如果确实需要应用层统一管理,再补齐错误分类、单次请求约束和任务预算。否则新增一层 helper,可能只是多增加一层尝试。
能拿来做什么
- 在 Node 的 AI API 适配层按服务方解析错误,将临时限流、账户操作和未知错误分开处理,避免仅凭
status === 429重试。 - 检查 SDK、队列和业务封装各自的重试设置,为一次用户操作确定统一的 HTTP 尝试次数与总耗时预算,并让每次请求遵守剩余时间。
- 为流式生成和工具调用记录执行阶段;已经产生输出或副作用时,先确认幂等或结果核对机制,再决定是否重放。
- 为限流故障建立脱敏记录,同时观察共享路由的并发和 token 工作量,用排队、削减输入输出和平滑流量减少持续碰限。