ENGINEERING PLAYBOOK

HTTP 429 限流与 Retry-After

429 表示请求频率触发了服务端限制。客户端应先读取 Retry-After，再使用带抖动的退避和请求幂等性判断；服务端则要明确限流维度、窗口和响应头。

适用人群：需要实现限流退避并避免重试风暴的客户端与 API 工程师

排查路径

  1. 确认限流按账号、IP、令牌还是资源维度执行。
  2. 解析 Retry-After 的秒数或 HTTP 日期格式。
  3. 为可重试请求配置上限、退避与随机抖动。
  4. 记录触发率、恢复时间和被限制操作。

执行步骤

  1. 保存 429 响应头并核对服务器时钟。
  2. 只重试幂等或明确支持幂等键的请求。
  3. 限制并发，避免多个工作线程同时恢复。
  4. 为重试设置次数和总耗时上限。
  5. 服务端发布清晰的限流指标与告警。

可复制命令与示例

查看 Retry-After

curl -sS -D - -o /dev/null https://example.test/api

带上限的退避伪代码

delay = min(cap, base * (2 ** attempt)) + random.uniform(0, jitter)
time.sleep(delay)

可复现任务记录

具体错误或任务

服务返回 429 后客户端立即并发重试，放大限流并延长恢复时间。

失败信号：HTTP 429、Retry-After 存在或缺失，单位时间请求数在重试后继续上升。

最小输入

一个可重复请求、状态行、响应头、客户端重试次数与并发上限。

验证命令或步骤

curl --silent --show-error --dump-header - --output /dev/null 'https://api.example.test/rate-limited'

预期输出

成功样本为 2xx；限流样本明确显示 429，并保留 Retry-After 供客户端解析。

失败输出

客户端忽略 Retry-After、无上限重试，或多个实例在同一时刻同步重试。

成功判据

重试次数有上限并加入抖动，按服务提示等待后恢复，且总体请求率下降而非放大。

本任务常见错误

  • 把所有 4xx 都自动重试
  • 忽略 Retry-After 的日期与秒数形式
  • 缺少全局并发和重试预算

资料与适用边界

429 与 Retry-After 语义依据 RFC 6585 和 RFC 9110；具体配额与窗口以服务端当前文档为准。

证据块复核日期：2026-09-04

相关站内页面

资料依据与复核边界

资料复核日期：2026-08-29