大模型接口 429 怎么排查：区分请求额度、令牌额度和并发积压

线上问答刚接入批量摘要后，最常见的现场不是接口彻底不可用，而是某一小段时间里 429 突然升高：客服对话在等，导入任务也在等，工程师一看报错就把重试次数加大，结果等待中的请求又堆出一层。429 的排查关键不在“多等几秒”，而在于先弄清楚到底碰到了请求数量、令牌总量，还是本地并发把瞬时流量推得太高。

触发信号：看到 429 先别立刻再发，把现场线索留下来

先从一个很容易复现的场景开始：客服工作台把十几条历史消息拼进上下文，导入任务又同时提交数十个摘要请求。它们各自看都不算异常，可一旦在同一分钟集中到达，服务端就可能拒绝其中一部分。此时先记录接口名称、模型名、发起时间、请求标识、输入与输出令牌估算值，以及响应头中与剩余量、重置时间有关的字段。

不同服务商的字段名称并不完全一致，不能照搬一套固定名字。以 OpenAI API 文档为例，响应会提供请求标识，并可能带有请求和令牌两个维度的限制、剩余量与重置时间信息。它们能把“偶然报错”变成可判断的线索：是总量临近边界，还是请求到达得太密。

快速判断：请求数量、令牌总量和并发积压分别长什么样

先不要急着改代码，拿刚才留下的记录做一次横向对照。请求数量先耗尽时，往往是一批很短的调用在很窄的时间窗里集中到达；令牌总量先耗尽时，单次内容可能不多，但上下文很长、返回上限偏大，或者批量请求总输入很重；并发积压则常表现为本地等待队列持续增长，前一批还没返回，后一批又被同时放行。

这一步的目的不是给 429 贴上唯一标签，而是缩小下一次改动的范围。Google 的 Gemini 文档同样把请求数、令牌数等限额分开说明，并提示 429 可能在资源耗尽时出现；因此，日志里只保留状态码而没有消耗维度，往往无法判断该减并发还是该缩短上下文。

处理步骤一：先给入口加一道并发闸门

对一个刚出现波动的接口，最稳妥的第一个改动通常不是提升重试次数，而是把同时在途的请求固定在一个可观察的上限内。比如先将摘要队列限制为 4 个并发，把在线对话留出单独的名额。这个数值不是通用答案：从较低值开始，观察成功率、平均等待时长和 429 比例，再逐步调整。

import asyncio


gate = asyncio.Semaphore(4)


async def ask_model(client, payload):
    async with gate:
        return await client.responses.create(**payload)

这段代码只解决“同时放行多少个”这一件事。真正接入时，别把所有来源都塞进同一把闸门：用户正在等待的对话、后台生成标签、夜间批量整理，应该有各自的优先级和队列。否则离线任务一旦突增，前台看起来就像接口突然变慢。

处理步骤二：重试要退避、带抖动，也要知道何时停下

429 有时是短暂拥塞，等待后可以恢复；但所有任务在同一秒重试，会把下一波请求再次叠在一起。做法是给等待时间加入随机抖动，并为单个任务设定有限次数。服务端如果给了明确的等待提示，应优先尊重该提示；没有提示时，再使用指数增长的短暂等待。

import random


def next_delay(attempt: int, retry_after: float | None = None) -> float:
    if retry_after is not None:
        return min(retry_after, 30.0)

    base = min(2 ** attempt, 30.0)
    return base + random.uniform(0.0, 0.5)

调用方还需要区分可再次尝试的短暂拒绝和需要人工确认的配置问题。Gemini 的故障排查文档把 429、503 归为可能需要退避的暂时性情况；如果连续等待后仍然失败，就不要让任务无限悬挂，而应写入失败原因并进入人工查看队列。这样既不会吞掉用户任务，也不会把同一请求反复推回拥塞入口。

处理步骤三：令牌压力高时，先删无效上下文再谈额度

如果记录显示长对话和大文档更容易触发限制，把上下文原样重复发送往往比并发问题更隐蔽。可以先做三件小事：只保留与当前问题有关的最近几轮内容；把历史摘要写成短的事实条目；把输出上限设置到任务真正需要的长度。它们减少的不只是成本，也能降低令牌总量在短时间内被吃满的概率。

这里不建议一开始就把上下文裁得过短。先为每个请求记录输入估算、输出长度和最终效果，再比较不同截断策略。比如客服场景可以保留最近对话与已确认的用户事实，知识整理场景可以分段处理并在最后合并结果。用任务目标来决定保留什么，比一个固定的字符数阈值更可靠。

回滚路径：优先保护线上交互，暂停可以晚点做的任务

当 429 比例已经影响用户，回滚动作应当简单且可验证：暂停新进入的批量摘要、降低后台队列并发、保留前台对话的独立名额，然后观察一个短周期内的成功率是否回升。不要一边扩大并发一边缩短上下文，否则很难知道是哪项改动产生了效果。

一个实用的降级策略是给离线任务打上可延后标记。它们收到 429 后不立刻占住前台通道，而是按退避时间重新排入后台；前台如果也收到限制，则向用户展示“正在稍后重试”的状态，并设置合理的超时提示。这样做的核心是控制工作量进入入口的节奏，而不是掩盖错误。

告警确认：把 429 从一条异常变成四个可看的指标

恢复后别马上关闭观察。至少持续看四项：429 占全部调用的比例、平均等待次数、在途数量或队列深度、输入与输出令牌的分布。再按接口、模型、调用身份和任务类型切分，才能看出是某个批量功能把压力拉高，还是某类长对话需要调整上下文策略。

告警阈值也不要只盯绝对次数。一分钟内出现两次 429，对很小的流量可能已经说明异常；对高流量服务则更适合看比例与连续时长。把这些指标和改动时间对齐，下一次再遇到峰值时就能快速判断限并发、退避还是上下文整理是否真正有效。

复盘项：下一次不用从异常文本重新猜

最后把本次发现写进运行记录：触发时间窗、受影响接口、请求数量与令牌量的特征、入口并发、采取的临时动作、恢复时的指标变化。对于依赖外部大模型的产品，这些记录比一次性的“提高额度”更有价值，因为不同模型、不同账户和不同任务形态都可能有各自的边界。

把 429 当成流量控制的反馈信号，而不是单纯的接口故障，处理顺序就会清晰：先保留线索，再确定压力维度，接着控制入口和等待节奏，最后用指标确认结果。这样即使服务商规则有所变化，团队也能用同一套观察方法快速收敛问题。

相关问题

429 和 503 的处理方式一样吗？

两者都可能是暂时性问题，退避等待通常有意义，但含义并不完全相同。429 更直接指向请求被限制或资源额度耗尽；503 往往意味着服务暂时不可用。排查时仍要以服务商文档、响应内容和实际指标为准。

只要限制并发，就不需要记录令牌数了吗？

仍然需要。并发闸门能削平瞬时峰值，却不能降低单个请求本身的上下文长度。长内容集中到达时，令牌总量仍可能成为先触及的边界。

为何不让所有失败任务立即再次尝试？

同一时刻再次发起会制造新的尖峰，任务越多越容易彼此放大。退避与随机抖动会把到达时间打散，有限次数和人工查看入口则防止单个任务长期占用资源。

能否用一个固定的并发数套在所有模型上？

不建议。模型、账户层级、请求大小和业务优先级都不同。先从较低并发起步，根据成功率、等待时长和令牌分布逐步调整，比直接复制别人的数值更稳妥。