TapCub 正式上线:统计、分析、客服一个平台免费用
术语表

什么是 API 限流?429 错误、Retry-After 与退避重试

API 限流是对客户端在一段时间内能发多少请求设的上限。讲清到底在数什么、限额怎么实现、429 和 Retry-After 的含义,以及怎样匀速发送、重试而不火上浇油。

陈屿 审核人 伊森·布鲁克斯 又称 限流 最后更新 2026 年 11 月 17 日 术语表

一句话回答

API 限流是服务端对客户端在一段时间内最多能发多少请求设定的上限。超出上限的请求会被拒绝,通常返回 HTTP 429 Too Many Requests,客户端需要等一等再重试。

公式: 重试前的等待 = 随机取 0 到 min(上限, 起始值 × 2^第几次) 之间的值

什么是 API 限流?

API 限流(rate limiting)是服务端对客户端在一段时间内能向 API 发多少请求设定的上限。客户端超过上限后,服务端会拒绝多出来的请求,通常返回 HTTP 状态码 429 Too Many Requests,等这个时间段过去或容量恢复后再接受新请求。限流是为了防止服务器过载,也防止某一个用量很大的客户端占满大家共用的容量。

对调用 API 的人来说,更有用的理解是:限额是一条关于速度的规则,不是故障。守规矩的客户端预料到自己偶尔会碰到它,按被告知的时间等待,能合并请求时就发更少、更大的请求。

到底在数什么

不同的服务数的东西不一样。微软的限流模式一文列出三种常见的计量方式:

计量对象限额示例对客户端意味着什么
操作次数每秒 20 个请求请求越少越好,请求体大小无所谓
数据量每分钟 2 GiB小请求没问题,大载荷才占额度
操作成本每秒 20,000 个请求单元一次昂贵的查询比一次便宜的查询占更多额度

第二个问题是「客户端」指谁。关于 429 的 HTTP 规范有意没有规定:怎么识别用户、怎么计数,都由服务端决定。实际中,计数器挂在 API 密钥、用户 ID、IP 地址或它们的组合上。这个选择很重要:按密钥限,不管你跑多少台机器,限额都跟着凭证走;按 IP 限,可能把同一个办公室网络里的所有人一起卡住。

限额常见的几种实现方式

方式怎么计数预期表现
固定窗口按时钟窗口(比如每分钟)计数,到边界清零简单,但边界处会出现突发:在每分钟 100 个的限额下,12:00:59 发 100 个、12:01:00 再发 100 个,两秒内就是 200 个
滑动窗口统计从现在往前 60 秒内的请求没有边界突发,限额更平滑
令牌桶每个请求拿走一个令牌,令牌按固定速度补充,桶的大小就是最大突发量允许短暂突发,持续速度受限。Stripe 把它作为自己请求限流器的核心
并发限制同一时刻在处理中的请求数慢请求会占着名额,发得再快也没用

服务方很少告诉你它用的是哪一种。把公布的数字当作可持续的速度,不要指望突发一定被允许。

被限流的响应长什么样

RFC 6585 定义了 429:用户在给定时间内发送了过多的请求。响应里可以带 Retry-After 头,说明要等多久。按 RFC 9110,Retry-After 的值是秒数或 HTTP 日期,比如 Retry-After: 120 表示两分钟。这个头是可选的,所以客户端没有它也得能正常工作。

有些 API 把等待时间放在 JSON 响应体里,并附带一个机器可读的错误码。判断时看错误码,不要看给人读的提示文字。

429 和 5xx 不一样。429 的意思是「你发得太快了」;500 类错误的意思是「我们这边出问题了」。两种都值得等一等再重试。其他大多数 4xx,比如请求体格式不对或密钥错误,再发一次还是同样的结果。

客户端该怎么应对

  1. 不要立刻重试。 窗口还是满的,立刻重试只会被拒绝,还增加负载。
  2. 服务端让等多久就等多久。 如果有 Retry-After(或等价字段),至少等这么长。
  3. 没有提示时,指数退避并加随机抖动。 每次尝试把最长等待时间翻倍,直到一个上限,然后在这个最大值以内随机选一个延迟。AWS 对重试客户端的分析发现,100 个客户端竞争时加上抖动,调用次数减少一半以上,因为客户端不再步调一致地重试。
  4. 限制重试次数。 试几次之后就放弃,把错误交出去。
  5. 只重试有可能恢复的。 429、5xx 和网络错误以后可能成功;其他大多数 4xx 不会。
  6. 重试时沿用同一个幂等键, 这样一个实际上已经成功的请求不会被算两次。

示例等待表:起始 1 秒,上限 60 秒,共六次。

第几次重试最长等待窗口完全抖动下的平均等待(窗口的一半)
11 秒0.5 秒
22 秒1 秒
34 秒2 秒
48 秒4 秒
516 秒8 秒
632 秒16 秒

最长可能的总等待是 1 + 2 + 4 + 8 + 16 + 32 = 63 秒;平均是 31.5 秒。

算例:匀速发送胜过盲目重试

示例数据:一项任务要向每分钟限 100 个的 API 发 1,000 个请求。假设是固定的一分钟窗口,客户端在下一个窗口开始时重试。

策略发出的请求数被拒绝完成用时
全部发出,每分钟把失败的再发一遍1,000 + 900 + 800 + … + 100 = 5,5005,500 − 1,000 = 4,50010 分钟
从一开始就每分钟发 100 个1,000010 分钟

两种做法都是十分钟完成,因为速度是由限额决定的。盲目重试的那种为此多发了 5.5 倍的流量,而且每个被拒绝的请求都还要记录和处理。合并请求是另一个办法:如果同一个 API 每个请求最多接受 50 条记录,同样的 1,000 条记录只要 20 个请求,一分钟内就发完。

匀速发送是有代价的,代价是延迟。数据到达的时间比没有限额时更晚,所以补数据之前要先算好需要多久。见数据延迟。

永远不返回 429 的限制

不是所有的限制都会明说。有些接收浏览器流量的接口会丢掉多余的请求,仍然返回成功状态,因为发送方拿到错误也做不了什么。这让 2xx 只能说明请求本身,说明不了留下了什么。

限流(rate limit)和配额(quota)也不一样。限流按很短的窗口计,几秒或几分钟后自己恢复。配额,比如每月的事件额度,按计费周期计,只有周期重置或套餐变更后才恢复。如果请求都成功了、数据却缺了,先查配额和报表,再怪限流。

常见误区

  • 没有延迟的重试循环。 它会把一个被拒绝的请求变成一场洪水。
  • 一条记录一个请求。 接口支持批量时,一千个单条请求用掉请求限额的一千个单位,一个批量请求只用一个。
  • 不理会服务端给的等待时间。 面对 12 秒的 retryAfter,固定睡 1 秒会再失败十一次。
  • 重试不会恢复的失败。 400、401、403 等一等也不会变成 200。
  • 多个工作进程共用一个密钥,却不共用限流器。 每个进程都没超限,总量却超了。让所有进程走同一个匀速发送机制。
  • 重试时不带幂等键。 实际上已经成功的请求会被算两次。

在 TapCub 里的限额

假设你要通过服务端事件接口,把数据库里 120,000 条历史订单补进 TapCub。

  1. 创建密钥。 在 配置 › 设置 › API 密钥 里创建勾选「服务端 Track」的密钥。密钥以 wck_ 开头,只显示一次。
  2. 先算账。 服务端行为事件(/api/v1/track)每个密钥每分钟允许 600 个请求,每个请求最多 1,000 个事件,请求体最大 2 MB。一个事件一个请求,就是 120,000 个请求 ÷ 600 = 200 分钟,约 3.3 小时。按每批 1,000 个发,是 120 个请求,只占一分钟额度的五分之一。
  3. 处理 429。 响应里 code 是 RATE_LIMIT,另有以秒计的 retryAfter。至少等这么久,再用同样的 insert_id 重发同一批,因为重试产生的重复会按 insert_id 去重。判断时看 code,不要看 message,它可能是中文。
  4. 或者让服务端 SDK 来做。 服务端 SDK 把事件排成队列,每 3 秒或攒到 200 个就发送,每个请求最多 1,000 个事件、1 MB。遇到网络错误、5xx 和 429 最多重试 5 次,从 0.5 秒开始翻倍、最长 30 秒,并遵守 Retry-After;其他 4xx 不重试。内存里最多等待 10,000 个事件,超过后最旧的会被丢弃,并报告为 QUEUE_FULL。
  5. 记住浏览器采集的处理方式不同。 网站脚本发来的浏览量按访客、IP 和站点限流,超出的事件被静默丢弃,采集端仍返回 202,所以没有 429 可以响应。到 网站统计 › 实时 看事件到没到。另外,每月事件配额是另一回事:超过上限后,采集请求仍返回 202,事件不会被存储。

另见:基本认证是什么?请求头怎么写,什么时候不该用。

另见:暴力破解攻击:原理与防范方法。

另见:Smurf 攻击:原理、放大算术与防御。

资料来源

这个解释清楚吗?

我们会根据反馈修改和补充这篇内容。

陈屿

技术工程师

专注统计代码、SDK 与接口集成文档,从接入验证到问题排查,帮助开发者更顺畅地完成实施。

常见问题

常见追问

大家看完定义后最常问的几个问题。

还有其他问题?

直接和 TapCub 团队聊聊——工作日通常几小时内回复。

HTTP 429 Too Many Requests 是什么意思?

意思是客户端在给定时间内发送了过多的请求。响应里可以带 Retry-After 头,说明要等多久。标准把怎么识别客户端、怎么计数留给每个服务端自己决定。

收到 429 后应该等多久?

至少等 Retry-After(或响应体里的等价字段)给出的时间。没有提示时,指数退避并加随机抖动,限制重试次数,试几次之后就放弃。

限流和节流有什么区别?

各家用法不同。按微软的说法,节流是服务对不愿全速处理的请求所做的限制,限流模式则是客户端给自己的请求匀速,使之保持在这些节流限制之内。

TapCub 服务端事件接口的限额是多少?

服务端事件接口每个 API 密钥每分钟允许 600 个请求,每个请求最多 1,000 个事件。超出限额时返回 429,错误码是 RATE_LIMIT,并带以秒计的 retryAfter。

在你自己的网站上看这个数字

加一行脚本就能开始,网站和 App 都能接,几分钟内就能看到第一批报表。

看清数据,找到增长。

每一次点击,都有数据依据。装好一行代码,1 分钟看到第一批数据。

无需信用卡 · 统计与客服都有免费版 · 统计无 Cookie