HTTP 429 Too Many Requests

HTTP 429 是什么意思

HTTP 429 Too Many Requests 表示客户端超出了速率限制——按 IP、按 API 密钥、按用户或按端点计算。行为规范的服务器会包含 Retry-After 头(秒数或日期),通常还会附带描述配额的 X-RateLimit-* 头。

对客户端而言,正确的反应始终一致:放慢速度。立即重试只会让情况恶化,甚至可能把临时限流升级为封禁。

429 错误的常见原因

• API 客户端轮询过于频繁,或突发流量超出了配额。
• 未在请求之间添加延迟的网页抓取。
• 一个 bug:没有退避机制的重试循环不断轰炸同一个端点。
• 共享 IP(办公室 NAT、VPN、无服务器出口)的合计流量超出了限制。
• 登录端点将重复尝试作为暴力破解防护进行限流。

作为客户端/开发者该如何修复

• 严格遵守 Retry-After;如果缺失,则使用带抖动的指数退避(例如 1 秒、2 秒、4 秒、8 秒……)。
• 读取 API 的 X-RateLimit-Remaining/重置 头,并主动控制请求节奏。
• 批量处理请求并缓存响应,而不是重复获取相同的数据。
• 把负载分散在时间上,而不是分散到临时 IP 上——规避限制通常违反 API 的使用条款。

作为 API 所有者该如何修复

• 始终发送 Retry-After 和配额相关的响应头,以便客户端能够合理应对。
• 尽可能按密钥/用户而非单纯按 IP 进行限流,以避免误伤共享网络。

示例响应

HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0

{"error":"rate_limited","retry_after":30}

常见问题