Claude Rate Exceeded 错误：先确认限制归属再重试
Claude API Error: Rate limit reached 不一定是额度用完：先分清订阅窗口、1M 权限、API key 和网关，再按各自的 reset 处理。
文章目录
如果 Claude 显示 "Rate Exceeded"，终端里出现 Claude API Error: Rate limit reached，或者 Claude Code 打出 429，不要先假设是同一个 API 配额耗尽。先确认限制来自哪一层：Claude.ai / Desktop 的套餐用量窗口、Claude Code 订阅登录、1M 上下文模型的套餐权限、Claude Code 里的 API key、Anthropic 直连 API、Bedrock / Vertex AI 项目、组织网关，还是服务端的临时限流。每一层的 reset 信号和该找的人都不同。
Claude API Error: Rate limit reached 这句笼统的报错要先看版本。截至 2026 年 10 月 5 日，Claude Code 的错误说明里已经没有这句原文，当前版本会按原因给出具体提示。旧版本则可能把权限问题也显示成它：Claude Code 2.1.89 的更新日志写明修复了"API 返回权限错误时显示误导性的 Rate limit reached"，2.1.78 修复了 VS Code 里订阅用户选 Opus 时因 1M 上下文变体报 "API Error: Rate limit reached" 的问题。也就是说，套餐用量明明还有剩、却每次请求都被这句话拦住时，先怀疑是不是选了套餐不直接包含的 1M 上下文模型，而不是额度用完。所以第一步是在当前版本里重现一次，读完整提示，再按下表对应。
| 使用入口 | 限制来自 | 先做什么 | 你会看到的提示或证据 | 下一步 |
|---|---|---|---|---|
| Claude.ai、Desktop、移动端 | Claude 套餐用量窗口或容量管理 | 能打开则看 Settings > Usage，缩短长对话/大文件，等待显示的 reset | 5 小时、session、weekly reset 文案，用量条，capacity 文案 | 开一个更小的新聊天、等待、开启 extra usage 或稍后重试 |
| Claude Code 订阅登录 | 与 Claude.ai 共享的套餐窗口 | 运行 /usage 看各项限额和 reset 时间 | You've hit your session limit · resets …，以及 weekly、Opus、Sonnet limit | session 和 weekly 限额所有模型共用，换模型没用，只能等 reset 或用 /usage-credits 加用量；Opus 或 Sonnet limit 只限该系列，可用 /model 换到别的系列 |
| Claude Code 选了 1M 上下文模型 | 套餐权限，不是额度 | 用 /model 看模型名是否带 [1m] | API Error: Usage credits required for 1M context；旧版本只显示 Rate limit reached | 换成不带 [1m] 的变体，或按提示开启 usage credits 后重启或新开会话 |
| Claude Code + API key | API key 所属 Console workspace 或云项目自己的速率限制 | 跑 /status 确认当前凭证；环境里遗留的 ANTHROPIC_API_KEY 会让请求绕开订阅、走低等级 key | API Error: Request rejected (429) | 减少并行 subagent 和工具并发，或在对应控制台申请更高等级 |
| Anthropic 直连 API | workspace 与组织的速率限制 | 有 retry-after 就按它等待，缩小请求 | HTTP 429、rate_limit_error、anthropic-ratelimit headers | 同一路由重试一个更小请求 |
| Bedrock、Vertex AI、网关 | 云项目、区域配额或网关的花费上限 | 先查云厂商控制台或网关日志 | ThrottlingException、区域配额；spend limit reached (daily; resets … UTC)；· 后面跟着 Too Many Requests 这类网页标题 | 调整对应配额，或请网关管理员调高上限；网关花费上限 Claude Code 不会自动重试 |
| 服务端临时限流、突发流量 | 服务负载或你的流量形状 | 短等、看状态页、慢启动、排队 | API Error: Server is temporarily limiting requests (not your usage limit)、近期 incident、并发尖峰 | 与套餐额度无关，Claude Code 会自动退避重试；持续出现再看 status.claude.com |
停止规则：归属没确认前，不要连续重试、不要换 key、不要升级套餐、不要换中转地址或开代理。换 key、换中转都是把请求交给另一个归属方，只会改变谁在限制你；错误消失也不等于诊断完成，可能只是你把证据换没了。
先确认是哪条路由产生限制
"rate limit reached" 只是症状，不等于所有情况都是同一个 API 桶。服务端直接请求 api.anthropic.com 时，证据在 HTTP 状态、响应体和 header。Claude Code 如果设置了 ANTHROPIC_API_KEY，终端请求可能走 API key 计费，而不是你以为的 Pro 或 Max 订阅。Bedrock、Vertex AI 或网关返回类似限流文案时，归属可能在云项目、区域、租户或代理策略。
先问三个问题：谁处理了这次凭证？哪个控制台拥有这个凭证？能否在不换模型、不换 provider、不改 prompt、不改 region 的前提下，同一路由复现一次？如果每次都换变量，你得到的是绕过，不是诊断。
如果终端报的其实是 500 或 529，按 Claude Code 500 和 529：中断后恢复原会话 处理，只继续未完成的工作。在 Claude Code 终端里逐步排查登录方式、用量窗口、上下文和 API key，见 Claude Code Rate Limit Reached 怎么办：认出限额类型，原会话续跑。
Claude.ai 或 Desktop：先看用量窗口
如果错误出现在 Claude.ai、Desktop 或移动端，并且没有 HTTP header，就先按产品表面的用量限制处理。官方帮助把 usage limits 和 length limits 分开：usage 是一段时间内能和 Claude 交互多少，length 是单个对话能承载多长上下文。长对话、大附件、Research、连接器、代码执行和更重的模型都会让窗口消耗得比“消息数”更快。
第一步不是 API 修复。能打开就看 Settings > Usage，读清楚 reset 时间；当前 thread 很大时开一个更小的新聊天；移除不必要的文件和工具；如果文案是容量约束，就稍后再试。容量管理不一定会显示为状态页 outage。
Anthropic 直连 API：先相信 header
直连 Anthropic API 的 HTTP 429 对应官方 rate_limit_error。真正有用的不是固定 tier 数字，而是 retry-after、anthropic-ratelimit 请求桶、输入 token 桶和输出 token 桶。月度额度还剩，不代表当前一分钟窗口没有耗尽；预算正常，也可能被 output token 或并发请求压住。
有一种 429 不能靠等几秒解决：响应里 error.details.error_code 是 enforced_spend_limit_reached 时，触发的是当前等级的强制月度上限，没有 retry-after，要等到下月 1 日 00:00 UTC 或申请提高后才恢复。你自己给组织或 workspace 设的花费上限通常返回 400 而不是 429。速率限制文档列出了这些情况和对应的响应头。
下一次请求要更小、更慢、更可测。按 retry-after 等待，减少并发，缩短实际输出（输出 token 桶按实际生成量计，max_tokens 本身不占额度），把大任务拆开，缓存稳定上下文，然后只在同一模型、同一凭证、同一路由上重试一个请求。
Claude Code：先查 active route
Claude Code 多了一层路由。/status 会告诉你当前认证路径；ANTHROPIC_API_KEY 会让请求走 API key workspace。不要用订阅升级去修 API-key 429，也不要用 API header 去解释订阅 session window。计费和权限归属可参考 Claude Code API Key 和订阅计费怎么选，配置边界见 Claude Code API 配置：先选路由，再设置 Key、模型和网关。
为什么用量看起来还够，请求却被挡
直连 API 的速率限制按令牌桶持续补充，不是到点整体清零；套餐用量则按 session 和 weekly 窗口计算。RPM、输入 token、输出 token、burst、provider quota 可以分别触发。一个长上下文会压输入 token；一个很长的回答会压输出 token；很多小请求会压 RPM；突然放大流量还可能触发 acceleration 控制。
修下一次请求，不要制造更多噪音
一次只改一个变量：加 jitter backoff，限制 worker 并发，缩短实际输出，把同步任务放进队列，记录 status、request_id、路由归属、model、workspace、region、retry-after 和 remaining/reset header。验证必须保持同一路由，否则错误消失也无法说明原问题。
如果团队里有人同时改 prompt、切模型、换网关和调 worker 数，这次排查就会失去价值。更稳妥的做法是先冻结失败路径，把最近一次成功请求、第一次失败请求和当前失败请求放在同一张表里比较。你要找的是哪个维度突然变化：请求数、输入 token、输出 token、区域、项目、租户、模型还是凭证。这个比较能把“服务不稳定”的直觉变成可操作的限流证据，也能避免把本应由网关处理的问题误报给 Anthropic。
provider 或 gateway 限制
通过 Bedrock、Vertex AI 或网关调用 Claude 时，Anthropic Console 不一定拥有这次失败。Bedrock 看 service quota 和 region，Vertex AI 看 project/location/model quota，网关看租户限额、上游策略和 per-key throttle。
升级前准备证据包
同路复现仍失败后再升级处理。证据包包括 exact message、时间与时区、request_id、response headers、model、workspace/project/region、路由归属、最近流量变化、状态页结果和最小复现请求。不要发送 API key、token、用户隐私内容或猜测性结论。
真正有用的升级不是长篇描述，而是一组能让对方复核的字段。对 Claude.ai 这类产品表面，要补上账号类型、显示的 reset 文案、是否启用 extra usage、是否有大文件/Research/连接器；对 Claude Code，要补上 /status 或 /usage 的结果；对直连 API，要补上 request_id 和 headers。对于直连 API，header 和 request_id 最关键；对于 Bedrock 或 Vertex AI，项目、区域和 quota 页面截图更关键；对于网关，租户 key、上游路由和限流策略更关键。把这些分清楚，support 才能判断应该扩容、等待窗口、修客户端排队，还是把问题转给正确的平台。
常见问题
Claude 报错 API Error: Rate limit reached，是额度用完了吗？
不一定。旧版 Claude Code 会把 1M 上下文模型的权限错误也显示成这句话，用量还有剩时尤其要先查 /model 里是否选了带 [1m] 的模型。当前版本会直接给出 session limit、Usage credits required for 1M context、Request rejected (429) 等具体提示，按开头的表格对应处理。
这个错误一定是 Anthropic 直连 API 429 吗？
不一定。直连 API 429 最清楚，但 Claude Code、云厂商、网关和 burst 控制都可能出现相近文案。
要不要先换 API key？
不要。先证明 active route。换 key 可能改变归属，让原错误无法复现。
为什么额度页面还显示可用？
因为月度额度、订阅窗口和持续补充的 RPM/token/burst 限制不是同一个东西；在 Claude Code 里，1M 上下文的权限检查也会在额度还有剩时拦下请求。
Claude Status 正常怎么办？
继续查本路由证据：直连 API 看 header，Claude Code 看 /status，云厂商看 quota，网关看日志。
什么时候联系 support？
同路验证仍失败且证据包完整时再联系对应归属方。
