首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >接口返回 429 怎么办:Retry-After、令牌桶和「一起重试」的坑,用 Python 实测

接口返回 429 怎么办:Retry-After、令牌桶和「一起重试」的坑,用 Python 实测

原创
作者头像
用户12904616
发布于 2026-11-21 12:41:56
发布于 2026-11-21 12:41:56
300
举报

先说结论: 对方返回 429 Too Many Requests,说明你发得比它允许的快。只在收到 429 之后按 Retry-After 等待再重试,请求最后能成功,但会产生大量无效请求:实测 30 个并发请求、对方限每秒 5 个,最后 30 个都成功了,中间却吃了 75 次 429,因为所有被拒的请求在同一时刻醒来、又一起撞上去。正确的做法是在发之前就限速:用令牌桶把速率压到对方限额以下。但令牌桶的「桶容量」要小心,容量设成 5、速率设成 5/秒时仍然有 7 次 429,原因是开头那一批突发加上之后补的令牌,在对方的同一个计数窗口里超过了 5 个;把速率降到 4.5/秒、容量 1,30 个请求 0 次 429,总耗时 6.5 秒,和硬撞差不多。下面在 macOS 上用 Python 3.9、aiohttp 3.13.5 复现,输出都是实际跑出来的。

测试服务:每秒 5 个,超了返回 429

服务端按固定窗口计数,每个 1 秒窗口最多放行 5 个,多出来的返回 429,并在 Retry-After 里告诉客户端几秒后再来:

代码语言:javascript
复制
win = {'start': 0.0, 'n': 0}

async def h(req):
    now = time.monotonic()
    if now - win['start'] >= 1.0:
        win.update(start=now, n=0)
    win['n'] += 1
    if win['n'] > 5:
        ra = max(1, round(1.0 - (now - win['start']) + 0.5))
        return web.Response(status=429, headers={'Retry-After': str(ra)})
    return web.Response(text='ok')

很多公开接口就是这种固定窗口或者近似的滑动窗口,限额写在文档或响应头(如 X-RateLimit-Limit、X-RateLimit-Remaining)里。

令牌桶

令牌桶按固定速率往桶里加令牌,桶满了就不再加;每发一个请求拿走一个令牌,没令牌就等:

代码语言:javascript
复制
class TokenBucket:
    def __init__(self, rate, capacity):
        self.rate, self.capacity = rate, capacity
        self.tokens, self.last = capacity, time.monotonic()
        self.lock = asyncio.Lock()

    async def take(self):
        async with self.lock:
            while True:
                now = time.monotonic()
                self.tokens = min(self.capacity, self.tokens + (now - self.last) * self.rate)
                self.last = now
                if self.tokens >= 1:
                    self.tokens -= 1
                    return
                await asyncio.sleep((1 - self.tokens) / self.rate)

rate 决定长期平均速率,capacity 决定允许多大的突发。

实测结果

每个用例一次性并发 30 个请求:

代码语言:javascript
复制
no limiter, give up on 429         n=30 ok=5   429=25   0.00s
no limiter, honor Retry-After      n=30 ok=30  429=75   5.04s
token bucket 5/s, capacity 5       n=30 ok=30  429=7    6.41s
token bucket 4.5/s, capacity 1     n=30 ok=30  429=0    6.49s
  1. 不限速、遇到 429 就放弃:只成功 5 个,25 个失败。
  2. 不限速、按 Retry-After 重试:全部成功,但多发了 75 次被拒的请求。原因是被拒的请求拿到的 Retry-After 相同,睡同样久,同时醒来,又一起超额。真实接口里,这种行为容易让你的 key 被更长时间封禁。
  3. 令牌桶 5/秒、容量 5:开头一口气发 5 个(桶是满的),之后每 0.2 秒补 1 个。对方的窗口从第一个请求开始算,窗口还没结束时已经补了几个令牌,于是同一窗口里超过 5 个,吃了 7 次 429。
  4. 令牌桶 4.5/秒、容量 1:不允许突发,速率略低于限额,0 次 429。总时间 6.49 秒,比第 2 种只多 1.4 秒,却少了 75 次无效请求。

实用写法

把限速和重试放在一起:

代码语言:javascript
复制
import random

async def fetch(session, bucket, url, max_retries=5):
    for attempt in range(max_retries + 1):
        await bucket.take()
        async with session.get(url) as r:
            if r.status != 429:
                r.raise_for_status()
                return await r.read()
            ra = r.headers.get('Retry-After')
        # Retry-After 可能是秒数,也可能是 HTTP 日期;这里只处理秒数
        wait = float(ra) if ra and ra.isdigit() else min(60, 2 ** attempt)
        await asyncio.sleep(wait + random.uniform(0, 0.5 * wait))   # 加随机抖动,避免一起醒来
    raise RuntimeError(f'429 重试 {max_retries} 次仍失败:{url}')

几个要点:

  • 速率设在限额的 80%~90%,桶容量设成 1 或很小的数,除非文档明确说允许突发;
  • 重试要加随机抖动,否则同一批请求会同步重试;
  • Retry-After 有两种格式:秒数(Retry-After: 2)或 HTTP 日期(Retry-After: Wed, 21 Oct 2026 07:28:00 GMT),日期格式用 email.utils.parsedate_to_datetime 解析;
  • 多进程或多台机器共用一个限额时,本地令牌桶不够,要把计数放到 Redis 这类共享存储里;
  • 看响应头:有 X-RateLimit-Remaining 的接口,可以在剩余为 0 之前主动放慢。

常见误区

  • 「收到 429 再说」:最后也能成功,但无效请求是有效请求的好几倍。
  • 「速率等于限额就行」:服务端的窗口和你的时钟对不齐,加上突发,等于限额时仍会超。
  • 「指数退避就够了」:没有抖动的指数退避,所有请求仍然一起醒来。
  • 「多开几个连接就快了」:限额通常按账号或 key 算,连接数多少不影响限额。

小结

  • 429 的根本解法是发之前限速,重试只是兜底;
  • 令牌桶速率略低于限额、容量尽量小;
  • 重试读 Retry-After,再加随机抖动;
  • 多个进程共用限额时,计数要放到共享存储里。

测试环境:macOS,Python 3.9.6,aiohttp 3.13.5,服务端和客户端都在本机。

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

目录
  • 测试服务:每秒 5 个,超了返回 429
  • 令牌桶
  • 实测结果
  • 实用写法
  • 常见误区
  • 小结
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档