

```
Status code: HTTP 429 (Too Many Requests)
Anthropic: error.type = rate_limit_error, plus a retry-after header
OpenAI: rate-limit 429 and spend/credit 429 share the code; read error.code
Google Gemini: 429 RESOURCE_EXHAUSTED, no retry hint documented
OpenRouter: 429 raised by OpenRouter, or relayed from the upstream provider
First thing to do: read retry-after, wait that long, retry once
No header: back off 1s, 2s, 4s with jitter, cap at 5 attempts
Never retry: credit/spend-cap 429s, they do not clear on their own
```

状态码本身几乎什么都告诉不了你。真正告诉你遇到的是五种问题中的哪一种的，是错误体和响应头，而这五种里有两种靠等待是解决不了的。

## 「429 Too Many Requests」到底是什么意思？

**它意味着你的凭证被接受了，请求却依然被拒绝，因为你的账户请求的流量超过了当前允许的额度。** 各厂商的措辞不同（「Rate limit reached for requests」、「rate limit exceeded」、`RESOURCE_EXHAUSTED`），但状态码是一样的。

429 不是以下三种情况：

- 认证失败。错误或被吊销的密钥是 401，没有资源访问权限的密钥是 403。

- 服务宕机。Anthropic 用 529 `overloaded_error` 表示「the API is temporarily overloaded」（API 暂时过载），这是面向所有用户的，与你自己的限额无关。

- 未必与你的流量有关。在路由服务上，429 可能来自上游供应商，只是被转发给了你。

限流窗口通常是一分钟，但它不是时钟意义上的一分钟。Anthropic 将其限流器记录为[令牌桶](https://platform.claude.com/docs/en/api/rate-limits)：「your capacity is continuously replenished up to your maximum limit, rather than being reset at fixed intervals.」（容量会持续补充到你的最大上限，而不是按固定间隔重置。）

## 速率超限错误是我的问题还是服务方的问题？

**大多数情况下都不是。它是针对你账户的一项策略决定，而有五种不同的策略会产生同一个状态码。**

| 你实际触发的是什么 | 它如何标识自己 | 等待能解决吗？ |
| --- | --- | --- |
| 每分钟请求或 token 上限 | Anthropic `rate_limit_error` + `retry-after`；OpenAI「Rate limit reached for requests」 | 能，按文档说明的时间等待即可 |
| 消费或额度上限 | OpenAI 的 `error.code` 为 `credit_balance_exhausted`、`organization_spend_limit_exceeded`、`project_spend_limit_exceeded`、`organization_usage_limit_exceeded` | 不能。重试只会白白消耗配额 |
| 加速限制（流量攀升过快） | Anthropic 在使用量陡增时返回 429，此时仍在你的名义限额之内 | 能，但正确做法是逐步爬坡 |
| 免费层每日上限 | OpenRouter 的 `:free` 模型：20 requests/minute、50 requests/day（购买额度低于 10 credits 时），达到 10+ 时为 1,000/day | 不能，得等到跨天才行 |
| 上游供应商容量 | OpenRouter 的 `error.metadata.provider_code` 携带供应商的原始代码 | 在同一条路由上重试只会更糟。改用故障转移 |

OpenAI 把这个区别说得很直白：`Retry-After`「does not mean that quota, billing, or other errors that require user action can be resolved by retrying.」（并不意味着配额、计费或其他需要用户处理的错误可以重试解决。）一个对所有 429 一视同仁的重试循环，会一直死磕一个已经耗尽的额度余额，直到你的告警系统察觉为止。

最后一行是人们最常误诊的。当一个发布期受限的模型无论你处于哪个层级都返回 429 时，在那条路由上再多的退避也无济于事，这正是 OpenRouter Kimi K3 429 问题的典型形态。

## 哪个响应头告诉你何时重试？

**读 `retry-after`。它是服务器直接告诉你的唯一数值，其余所有响应头都只是上下文。** 剩下的这套响应头因厂商而异，包括重置值的格式。 标准的 `Retry-After` 响应头会以秒数或 HTTP 日期格式告知客户端等待时长，部分提供商如 OpenAI 还会附带 `x-ratelimit-reset-requests` 等自定义头字段，而这类聚合网关路由请求时，网关层可统一解析上游各异的限速头并向下游暴露一致的重试信号。

| 厂商 | 响应头 | 重置格式 |
| --- | --- | --- |
| Anthropic | `retry-after`、`anthropic-ratelimit-requests-{limit,remaining,reset}`、`anthropic-ratelimit-input-tokens-*`、`anthropic-ratelimit-output-tokens-*`、`anthropic-ratelimit-tokens-*` | RFC 3339 时间戳 |
| OpenAI | `Retry-After`、`x-ratelimit-{limit,remaining,reset}-requests`、`x-ratelimit-{limit,remaining,reset}-tokens`，外加项目范围的 `*-project-tokens` | 时长字符串（`1s`、`6m0s`） |
| Google Gemini | 速率限制路径未做文档说明（not documented）；文档改为建议使用指数退避 | 无 |
| OpenRouter | 当 OpenRouter 自身限流时返回 `X-RateLimit-Limit`、`X-RateLimit-Remaining`、`X-RateLimit-Reset`；当供应商侧限制迫使重试时返回 `Retry-After` | 成功响应上不返回 |

那张表里有两个坑：

- **各厂商的重置值类型并不相同。** Anthropic 返回一个用于和时钟对比的时间戳。OpenAI 返回一个 Go 风格的时长，你需要把它解析成一段间隔。假设只有一种格式的代码，在遇到另一种时会悄无声息地产出垃圾数据。

- **Anthropic 会把剩余 token 数向最接近的千位取整**，所以把 `anthropic-ratelimit-input-tokens-remaining` 当作精确值来用，在小请求上会高估。

响应头是否存在也无法保证，这在网关上尤其重要。在 2026-08-10 一个 OpenAI 兼容端点测试四个模型时，有两条路由返回了完整的 `x-ratelimit-limit-requests` / `-limit-tokens` / `-remaining-*` / `-reset-*` 集合（外加一个非标准的 `x-ratelimit-renewalperiod-requests: 60`），另外两条则完全没有返回任何速率限制响应头。这套响应头属于实际提供模型服务的那一方，而不属于你调用的那个端点。写解析器时，要让缺失的响应头退化为退避，而不是抛出异常。

## 收到 429 后应该等多久？

**`retry-after` 说多久就等多久，如果没有这个响应头，就按 1s、2s、4s 加抖动，最多重试五次。** 固定睡眠时间是错误答案，因为每个并行 worker 都会在同一瞬间醒来，再次触发同一个限制。

| 重试次数 | 基础延迟 | 加上完全抖动后实际睡眠 |
| --- | --- | --- |
| 1 | 1s | 0 to 1s |
| 2 | 2s | 0 to 2s |
| 3 | 4s | 0 to 4s |
| 4 | 8s | 0 to 8s |
| 5 | 16s | 0 to 16s |

抖动是人们最常省略的部分，也正是当 20 个 worker 一起撞墙时最关键的部分。

```
import random, time
from openai import OpenAI, RateLimitError

client = OpenAI(base_url="")

def call_with_backoff(**kwargs):
 for attempt in range(5):
 try:
 return client.chat.completions.create(**kwargs)
 except RateLimitError as e:
 # the SDK unwraps the envelope, so e.body is the inner "error" object
 code = e.body.get("code") if isinstance(e.body, dict) else None
 if code in {"credit_balance_exhausted", "organization_spend_limit_exceeded"}:
 raise # a spend cap does not clear by waiting
 retry_after = e.response.headers.get("retry-after")
 delay = float(retry_after) if retry_after else random.uniform(0, 2 ** attempt)
 time.sleep(delay)
 raise RuntimeError("still rate limited after 5 attempts")
```

在写那个循环之前，先看看你的 SDK 是不是已经做了。查看已安装的 `openai` 2.53.0 客户端：`DEFAULT_MAX_RETRIES` is 2（默认最大重试次数为 2），重试路径先解析 `retry-after-ms`，然后是 `retry-after`（秒，或 HTTP 日期），会遵守服务器指定的延迟直到 120 seconds，若服务器要求的时间超过这个值则完全不重试。没有响应头时，它按 `0.5 * 2^n` 退避，上限为 8 seconds，再乘以一个介于 0.75 和 1.0 之间的抖动因子。Anthropic 的 SDK 默认也会对瞬时故障重试两次，并遵守 `retry-after`。所以在默认设置下，一个浮现到你代码里的 429，其实已经失败了三次（three times），每次之间仅间隔约半秒（half a second）和一秒（one second），离一分钟长的窗口差得远。要么调高 `max_tokens`……更准确地说，调高 `max_retries` 或自己接管这个循环；不要在第一层重试之上再叠加第二层重试。

## RPM、TPM、ITPM 和 OTPM 到底在计什么？

**不同厂商计量的东西不同，而单位决定了哪个旋钮有用。** RPM 统计每分钟请求次数，TPM 统计每分钟总 token 数，而 ITPM 与 OTPM 则分别单独计量输入 token 和输出 token，OpenAI、Anthropic 等主流提供商对这四个维度设有独立配额，使用 OpenRouter 或 等多后端网关时，需了解网关是否会将这些计量指标分别透传，以便准确判断触发了哪一层限制。

- RPM 计的是调用次数，而非大小。如果你总是撞到它，那就往每次调用里塞更多工作。

- TPM 是输入和输出共用的一个合并预算。OpenAI 对某些模型还额外叠加了 RPD、TPD 和 IPM（每分钟图片数）。

- ITPM 和 OTPM 是 Anthropic 把该预算拆开的结果，按模型类别分别管控，所以长上下文的工作负载和长输出的工作负载会撞到不同的墙。

- 缓存读取是个有趣的例外。在大多数 Claude 模型上，`cache_read_input_tokens` 不计入 ITPM，而 `cache_creation_input_tokens` 会计入。Anthropic 自己的例子：在 2,000,000 ITPM 限额下，若缓存命中率为 80%，每分钟约可处理 10,000,000 个总输入 token。

- `max_tokens` 不计入 OTPM，OTPM 是按实际产出的 token 来评估的。一个宽松的上限在速率限制上不会让你付出任何代价。

- 并发限制是另一码事。有些供应商限制的是在途请求数，而非每分钟速率，五家厂商速率限制对比里有各层级的具体数字。

## 为什么我流量很小却还是收到 429？

**因为每分钟限制很少真的按每分钟来管控，而且这个桶也很少只属于你一个人。** 常见嫌疑对象：

- 亚分钟级管控。Anthropic 的文档说得很明白：「a rate of 60 requests per minute (RPM) might be enforced as 1 request per second. Short bursts of requests can exceed the limit and trigger rate limit errors.」（每分钟 60 个请求的速率可能被按每秒 1 个请求来管控。短暂的突发请求会超出限制并触发速率限制错误。）

- 整个组织共用一个桶。限额挂在组织层级，而非每个密钥，所以除非你设置了工作区级别的限额，否则每个服务、notebook 和 CI 任务都从同一个池子里取用。

- 扇出。并行的智能体会成倍增加并发请求，且每个请求都携带完整上下文，所以 ITPM 会最先耗尽。

- 加速限制。使用量的陡增可能在你仍处于所声明的限额之内时就触发 429。

- 免费层每日上限。50 个请求的每日额度，一个下午的调试就用光了。

- 伪装成流量问题的计费 429。零流量却收到 429，通常意味着消费上限或额度余额耗尽，而不是吞吐量问题。

如果你是在一个编码智能体内部而非自己的代码里看到这个的，机制相同但旋钮不同，Claude Code 速率限制排查指南里讲了并发相关的设置。

## 429 和 529 或 RESOURCE_EXHAUSTED 是一回事吗？

**不是。429 关乎你的账户，529 和 503 关乎服务方，而 `RESOURCE_EXHAUSTED` 是 Google 对 429 的叫法。** 429 是 HTTP 标准状态码，表示客户端超出速率限制；529 是部分服务商（如 Anthropic）在系统过载时返回的非标准码；gRPC 体系中的 `RESOURCE_EXHAUSTED` 语义与 429 最为接近，三者触发原因和重试策略存在差异，OpenRouter 与 等网关层通常会将这些异构错误码归一化后再透传给调用方。

| 代码 | 厂商措辞 | 谁的问题 | 该怎么办 |
| --- | --- | --- | --- |
| 429 | `rate_limit_error`（Anthropic）、rate limit reached（OpenAI） | 你账户的限额或计费 | 读错误体，然后等待或处理计费 |
| 429 `RESOURCE_EXHAUSTED` | Google Gemini | 你的配额（RPM、TPM、RPD） | 指数退避，或申请配额 |
| 529 | `overloaded_error`（Anthropic） | 服务方容量，所有人 | 退避，或故障转移到另一个模型 |
| 503 | Service unavailable / `UNAVAILABLE` | 服务方容量 | 退避后重试 |
| 500 | `api_error` | 服务方 bug 或故障 | 带退避重试，然后附上请求 ID 上报 |

这个区分值得在你的日志里落实。一个把「429 + 529」当成一个数字来统计的仪表盘，没法告诉你到底该购买更高层级还是该增加一条兜底路由。如果你想深入了解容量这一类情况，请看 Claude API 529 过载指南。

只盯 Claude 一家的话，Claude API 报错汇总（429/401/529/超时）那篇按错误码逐个拆得更细，包括 402 余额不足和 streaming 中途报错这些本文没展开的分支。

## 怎样才能不再收到 429？

大致按「每单位缓解所需付出的努力」排序：

- 遵守 `retry-after`，并在它缺失时加抖动。免费，而且能修复你自己造成的那部分。

- 限制客户端侧的并发。在你的 worker 池外围加一个信号量，比任何重试策略都更可靠，因为它是预防突发，而不是在突发之后被动反应。

- 缓存你的前缀。在 Claude 模型上这能买到实实在在的 ITPM 余量，而不仅仅是更便宜的账单，提示缓存成本算账里展示了盈亏平衡点在哪。

- 把不紧急的工作转到批处理端点。批处理 API 有独立的限额，而且通常是半价（usually half price）。

- 与其更用力地重试，不如故障转移。当 429 来自上游容量时，对同一请求形态换用第二个模型，一跳就能恢复调用。这正是「一个端点后面挂多个模型」这一做法的实际理由： 是 OpenAI 兼容的，所以兜底只需改一个模型字符串，而不必做第二套集成。

- 申请提额。Anthropic 在控制台里有一个「Request rate limit increase」（申请提高速率限制）的流程，OpenAI 则根据累计消费把账户提升层级。两者都不是即时生效的，所以这是下个月的计划，而不是今天下午的方案。

有两件事不要做：不要把一个工作负载分散到同一组织下的多个 API 密钥上（限额是组织级别的，所以什么都不会改变），也不要在你并没有真的生成那么多 token 的情况下，寄希望于降低 `max_tokens` 来缓解输出限制。

## 本次更新查证的来源

- [https://platform.claude.com/docs/en/api/rate-limits](https://platform.claude.com/docs/en/api/rate-limits)

- [https://platform.claude.com/docs/en/api/errors](https://platform.claude.com/docs/en/api/errors)

- [https://developers.openai.com/api/docs/guides/rate-limits](https://developers.openai.com/api/docs/guides/rate-limits)

- [https://developers.openai.com/api/docs/guides/error-codes](https://developers.openai.com/api/docs/guides/error-codes)

- [https://ai.google.dev/gemini-api/docs/rate-limits](https://ai.google.dev/gemini-api/docs/rate-limits)

- [https://ai.google.dev/gemini-api/docs/troubleshooting](https://ai.google.dev/gemini-api/docs/troubleshooting)

- `https://openrouter.ai/docs/api-reference/limits`

---

**参考来源**

- ofox 文档：上游故障自动转移 — https://docs.ofox.io/zh/develop/advanced/fallback


状态码本身几乎什么都告诉不了你。真正告诉你遇到的是五种问题中的哪一种的，是错误体和响应头，而这五种里有两种靠等待是解决不了的。

429 Too Many Requests 错误详解：含义解析与重试策略指南

后端

网络与通信

编程语言

HTTP 429错误并非单一问题，而是账户限额、计费、加速限制等五种策略的统称。仅靠等待无法解决所有情况，需通过错误体和响应头区分。正确做法是解析retry-after头并采用指数退避，同时注意各厂商响应头格式差异，避免盲目重试耗尽配额。

代码解释

服务器

智能体

路由

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

429 Too Many Requests 错误详解：含义解析与重试策略指南-腾讯云开发者社区-腾讯云

429 Too Many Requests 错误详解：含义解析与重试策略指南

429 Too Many Requests 错误详解：含义解析与重试策略指南

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐