一句话回答
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,比如请求体格式不对或密钥错误,再发一次还是同样的结果。
客户端该怎么应对
- 不要立刻重试。 窗口还是满的,立刻重试只会被拒绝,还增加负载。
- 服务端让等多久就等多久。 如果有
Retry-After(或等价字段),至少等这么长。 - 没有提示时,指数退避并加随机抖动。 每次尝试把最长等待时间翻倍,直到一个上限,然后在这个最大值以内随机选一个延迟。AWS 对重试客户端的分析发现,100 个客户端竞争时加上抖动,调用次数减少一半以上,因为客户端不再步调一致地重试。
- 限制重试次数。 试几次之后就放弃,把错误交出去。
- 只重试有可能恢复的。
429、5xx和网络错误以后可能成功;其他大多数4xx不会。 - 重试时沿用同一个幂等键, 这样一个实际上已经成功的请求不会被算两次。
示例等待表:起始 1 秒,上限 60 秒,共六次。
| 第几次重试 | 最长等待窗口 | 完全抖动下的平均等待(窗口的一半) |
|---|---|---|
| 1 | 1 秒 | 0.5 秒 |
| 2 | 2 秒 | 1 秒 |
| 3 | 4 秒 | 2 秒 |
| 4 | 8 秒 | 4 秒 |
| 5 | 16 秒 | 8 秒 |
| 6 | 32 秒 | 16 秒 |
最长可能的总等待是 1 + 2 + 4 + 8 + 16 + 32 = 63 秒;平均是 31.5 秒。
算例:匀速发送胜过盲目重试
示例数据:一项任务要向每分钟限 100 个的 API 发 1,000 个请求。假设是固定的一分钟窗口,客户端在下一个窗口开始时重试。
| 策略 | 发出的请求数 | 被拒绝 | 完成用时 |
|---|---|---|---|
| 全部发出,每分钟把失败的再发一遍 | 1,000 + 900 + 800 + … + 100 = 5,500 | 5,500 − 1,000 = 4,500 | 10 分钟 |
| 从一开始就每分钟发 100 个 | 1,000 | 0 | 10 分钟 |
两种做法都是十分钟完成,因为速度是由限额决定的。盲目重试的那种为此多发了 5.5 倍的流量,而且每个被拒绝的请求都还要记录和处理。合并请求是另一个办法:如果同一个 API 每个请求最多接受 50 条记录,同样的 1,000 条记录只要 20 个请求,一分钟内就发完。
匀速发送是有代价的,代价是延迟。数据到达的时间比没有限额时更晚,所以补数据之前要先算好需要多久。见数据延迟。
永远不返回 429 的限制
不是所有的限制都会明说。有些接收浏览器流量的接口会丢掉多余的请求,仍然返回成功状态,因为发送方拿到错误也做不了什么。这让 2xx 只能说明请求本身,说明不了留下了什么。
限流(rate limit)和配额(quota)也不一样。限流按很短的窗口计,几秒或几分钟后自己恢复。配额,比如每月的事件额度,按计费周期计,只有周期重置或套餐变更后才恢复。如果请求都成功了、数据却缺了,先查配额和报表,再怪限流。
常见误区
- 没有延迟的重试循环。 它会把一个被拒绝的请求变成一场洪水。
- 一条记录一个请求。 接口支持批量时,一千个单条请求用掉请求限额的一千个单位,一个批量请求只用一个。
- 不理会服务端给的等待时间。 面对 12 秒的
retryAfter,固定睡 1 秒会再失败十一次。 - 重试不会恢复的失败。
400、401、403等一等也不会变成200。 - 多个工作进程共用一个密钥,却不共用限流器。 每个进程都没超限,总量却超了。让所有进程走同一个匀速发送机制。
- 重试时不带幂等键。 实际上已经成功的请求会被算两次。
在 TapCub 里的限额
假设你要通过服务端事件接口,把数据库里 120,000 条历史订单补进 TapCub。
- 创建密钥。 在 配置 › 设置 › API 密钥 里创建勾选「服务端 Track」的密钥。密钥以
wck_开头,只显示一次。 - 先算账。 服务端行为事件(
/api/v1/track)每个密钥每分钟允许 600 个请求,每个请求最多 1,000 个事件,请求体最大 2 MB。一个事件一个请求,就是 120,000 个请求 ÷ 600 = 200 分钟,约 3.3 小时。按每批 1,000 个发,是 120 个请求,只占一分钟额度的五分之一。 - 处理
429。 响应里code是RATE_LIMIT,另有以秒计的retryAfter。至少等这么久,再用同样的insert_id重发同一批,因为重试产生的重复会按insert_id去重。判断时看code,不要看message,它可能是中文。 - 或者让服务端 SDK 来做。 服务端 SDK 把事件排成队列,每 3 秒或攒到 200 个就发送,每个请求最多 1,000 个事件、1 MB。遇到网络错误、
5xx和429最多重试 5 次,从 0.5 秒开始翻倍、最长 30 秒,并遵守Retry-After;其他4xx不重试。内存里最多等待 10,000 个事件,超过后最旧的会被丢弃,并报告为QUEUE_FULL。 - 记住浏览器采集的处理方式不同。 网站脚本发来的浏览量按访客、IP 和站点限流,超出的事件被静默丢弃,采集端仍返回
202,所以没有429可以响应。到 网站统计 › 实时 看事件到没到。另外,每月事件配额是另一回事:超过上限后,采集请求仍返回202,事件不会被存储。
另见:暴力破解攻击:原理与防范方法。
资料来源
- IETF,RFC 6585, Additional HTTP Status Codes, section 4: 429 Too Many Requests。
- IETF,RFC 9110, HTTP Semantics, section 10.2.3: Retry-After。
- Microsoft Azure Architecture Center,Rate Limiting pattern。
- Stripe,Scaling your API with rate limiters。
- AWS Architecture Blog,Exponential Backoff And Jitter。
这个解释清楚吗?
我们会根据反馈修改和补充这篇内容。
提交没有成功,请稍后再试。
谢谢你的反馈,我们会据此改进这篇内容。你已经反馈过这篇了,谢谢。
