HTTP 状态码 429 Too Many Requests 限流了

FreeGuideOnline 最新 2026-07-05

什么是 HTTP 429 状态码？

HTTP 429 Too Many Requests 是一个客户端错误响应状态码，表示用户在 给定的时间内发送了过多请求，触发了服务器的访问频率限制机制，也就是我们常说的“限流”或“速率限制”。

与大多数 4xx 错误不同，429 的出现并不是因为请求本身有问题（如权限不足或资源不存在），而是因为 请求的数量 超过了服务器允许的阈值。这是一种典型的保护措施，目的包括：

防止滥用：避免单一用户消耗过多服务器资源。
保证公平：确保所有用户都能公平地访问 API 或网站。
抵御攻击：有效缓解 DDoS 攻击或暴力破解尝试。

当你看到这个状态码时，服务器正在明确地告诉你：“请慢一点，不要再发送请求了。”

它是如何工作的？—— 限流机制详解

服务器通常通过以下几种方式来判断是否应该返回 429 状态码：

固定窗口计数器：将时间线划分为固定大小的窗口（如每分钟），统计每个窗口内的请求数。实现简单，但在窗口边界可能发生流量突增。
滑动窗口日志：记录每个请求的时间戳，当新请求到达时，检查过去一段时间（如最近1分钟）内的请求总数。更平滑，但消耗更多内存。
滑动窗口计数器：结合了前两种的优点，既平滑又节省资源。
令牌桶：以恒定速率向桶中放入令牌，每个请求需要从桶中取出一个令牌。桶有最大容量，允许一定程度的突发流量。这是一种非常灵活且常用的算法。
漏桶：将请求视为水滴，漏桶以固定速率“漏出”请求。输入速率可以波动，但输出速率恒定，能够强制平滑流量。

无论采用哪种算法，一旦用户在给定的时间单位内的请求量超过限制，服务器就会在后续的响应中返回 429 Too Many Requests。

读懂服务器返回的重要信息

当收到 429 错误时，不要只关注状态码本身。服务器的响应头和响应体通常包含了帮助你恢复请求的关键线索。

1. 关键响应头：`Retry-After`

这是处理 429 错误时最重要的响应头。它告诉你在 重新发起请求之前需要等待多长时间。它的值可以是两种形式：

相对时间（秒数）：Retry-After: 120，表示 120 秒（2分钟）后再试。
绝对时间（HTTP 日期格式）：Retry-After: Wed, 21 Oct 2015 07:28:00 GMT，表示等到这个精确的时间点后再试。

示例响应头：

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 3600
...

2. 自定义速率限制头（非标准但常见）

很多大型 API 提供商会使用以 X-RateLimit- 开头的自定义头，让你更清晰地了解当前的限额状态，便于你动态调整请求策略。

响应头	含义描述
`X-RateLimit-Limit`	当前时间窗口内的总请求配额。
`X-RateLimit-Remaining`	当前时间窗口内剩余的可用请求数。
`X-RateLimit-Reset`	配额重置的时间点（通常是 Unix 时间戳）。

示例响应头：

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1695224400

3. 响应体

为了提供更好的开发体验，服务器通常会在响应体中给出人类可读的错误信息，例如：

{
  "error": {
    "code": 429,
    "message": "API rate limit exceeded. Please retry after 60 seconds.",
    "retry_after_seconds": 60
  }
}

作为 API 使用者，如何正确应对 429 错误？

遇到 429 错误，你的第一反应不应该是愤怒，而应该是 优雅地退避和重试。以下是最佳实践步骤：

1. 检查并遵守 `Retry-After` 头

这是服务器的直接指令，优先级最高。如果存在这个头，你的客户端必须在指定的时间间隔内暂停所有对该接口的请求。

2. 实现指数退避和抖动

如果响应中没有 Retry-After 头，你需要自己实现重试策略。最有效的方法是 指数退避+随机抖动。

指数退避：每次重试的等待时间呈指数增长，例如第1次等1秒，第2次等2秒，第3次等4秒，第4次等8秒…
随机抖动：在每次等待时间上增加一个随机毫秒数，避免多个客户端在同一时间点一起重试，造成“惊群效应”。

伪代码示例：

import time
import random
import requests

def request_with_retry(url, max_retries=5):
    for attempt in range(max_retries):
        response = requests.get(url)
        if response.status_code == 429:
            if 'Retry-After' in response.headers:
                wait_time = int(response.headers['Retry-After'])
            else:
                # 指数退避：2^attempt 秒，加上 0-1000ms 的随机抖动
                wait_time = (2 ** attempt) + random.uniform(0, 1)
            
            print(f"收到429，将在 {wait_time:.2f} 秒后重试...")
            time.sleep(wait_time)
        elif response.status_code == 200:
            return response.json()
        else:
            response.raise_for_status()
    
    raise Exception(f"请求失败，已达到最大重试次数 {max_retries}")

3. 主动减速：使用配额感知策略

不要等到被拒绝才减速。你应该监控 X-RateLimit-Remaining 头，当剩余请求量低于某个阈值（如 20%）时，主动降低你的请求速率，引入人工延迟。这能将触发 429 的概率降到最低。

4. 为请求添加排队机制

对于高频、并发的请求，在本地实现一个 请求队列 或 令牌桶，主动控制向外发送请求的速率，使其始终低于服务器限制。

5. 实现带断路器的重试

当重试持续失败多次时，应立即停止重试并抛出错误，避免无意义地消耗本地和服务器资源。这种“熔断”机制可以有效保护依赖系统的整体健康。

作为 API 设计者，如何设计一个好的限流系统？

如果你正在开发 Web API，合理地返回 429 错误是构建稳健 API 的关键一环。

1. 选择适合的限流粒度

根据你的服务特性，可以从不同维度进行限制：

按用户：根据用户 ID 或 API 密钥限制。这是最常见的。
按 IP 地址：对于未认证的公共接口很有用。
按端点：对计算密集型或数据库密集型的特定端点设置更严格的限制。

2. 必须返回 `Retry-After` 头

这是标准做法，能极大改善客户端的开发者体验。明确告知等待时长，避免客户端盲目猜测。

3. 透明地暴露速率限制状态

推荐使用 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset 这几个头，让客户端可以自我调控。这是一种无声的协议，能让双方合作得更好。

4. 在响应体中提供详细且有帮助的错误信息

返回结构化的 JSON 错误，不仅要说明“请求过多”，还要解释为什么被限制、当前的限制是什么、以及何时可以重试。

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "You have exceeded the rate limit of 100 requests per minute.",
    "limit": 100,
    "remaining": 0,
    "reset_at": "2023-09-20T12:00:00Z",
    "retry_after_seconds": 45
  }
}

5. 考虑使用 429 的替代方案（谨慎使用）

在某些极端情况下，你可能会对恶意流量直接返回 403 Forbidden 或直接丢弃连接。但对于普通用户因为正常使用而触发的限流，429 是标准且正确的选择。

不同技术栈下的限流实现概览

Node.js (Express) 使用 `express-rate-limit`

const rateLimit = require('express-rate-limit');

const limiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15分钟
  max: 100, // 在窗口期内每个 IP 最多100个请求
  standardHeaders: true, // 返回 `RateLimit-*` 头
  legacyHeaders: false, // 禁用 `X-RateLimit-*` 头
  message: {
    error: 'Too many requests, please try again later.',
    retryAfter: '15 minutes'
  }
});

// 对所有请求应用限流中间件
app.use(limiter);

Python (Flask) 使用 `flask-limiter`

from flask import Flask
from flask_limiter import Limiter
from flask_limiter.util import get_remote_address

app = Flask(__name__)
limiter = Limiter(
    app,
    key_func=get_remote_address,
    default_limits=["200 per day", "50 per hour"]
)

@app.route("/api/data")
@limiter.limit("10 per minute") # 对特定路由设置更严格的限制
def get_data():
    return {"data": "Here is your data"}

Nginx 作为反向代理的限流

http {
    # 定义一个共享内存区域，用于追踪请求状态。
    # 10m 可以存储约16万个IP的会话信息。
    # rate=10r/s 表示每秒处理10个请求，多余的会被延迟或拒绝。
    limit_req_zone $binary_remote_addr zone=one:10m rate=10r/s;

    server {
        location /api/ {
            # 允许最多20个请求的突发，其中10个请求会立即处理，其余按指定速率处理。
            limit_req zone=one burst=20 nodelay;
            
            # 当请求被拒绝时，返回429状态码
            limit_req_status 429;

            proxy_pass http://my_backend;
        }
    }
}

总结

HTTP 429 状态码不是简单的错误，而是一个设计精良的 流量控制信号。

对于 API 使用者，核心准则是：尊重 Retry-After 头，实施指数退避与抖动，并主动从响应头中读取限额状态进行自我调节。
对于 API 设计者，核心准则是：返回 Retry-After 头，提供透明的速率限制信息，并给出清晰的可操作错误信息。

理解了这背后的原理和最佳实践，你不仅能优雅地解决 “Too Many Requests” 的报错，还能设计出更稳定、更公平、更专业的网络服务。