# Claude Rate Exceeded 错误：先确认限制归属再重试

> Claude API Error: Rate limit reached 不一定是额度用完：先分清订阅窗口、1M 权限、API key 和网关，再按各自的 reset 处理。

- URL: https://blog.laozhang.ai/zh/posts/claude-rate-exceeded-error
- Published: 2026-05-09
- Updated: 2026-10-05
- Author: LaoZhang AI Team (https://blog.laozhang.ai/zh/about)
- Topic: Claude 与 Anthropic
- Tags: Claude, Rate Limit, Claude Code, Anthropic API

---
如果 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 的错误说明](https://code.claude.com/docs/en/errors)里已经没有这句原文，当前版本会按原因给出具体提示。旧版本则可能把权限问题也显示成它：Claude Code 2.1.89 的[更新日志](https://raw.githubusercontent.com/anthropics/claude-code/main/CHANGELOG.md)写明修复了"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：中断后恢复原会话](https://blog.laozhang.ai/zh/posts/claude-code-500-529-rate-limit) 处理，只继续未完成的工作。在 Claude Code 终端里逐步排查登录方式、用量窗口、上下文和 API key，见 [Claude Code Rate Limit Reached 怎么办：认出限额类型，原会话续跑](https://blog.laozhang.ai/zh/posts/claude-code-rate-limit-reached)。

![订阅登录、API Key、云平台与组织网关的证据入口](https://blog.laozhang.ai/posts/zh/claude-rate-exceeded-error/img/request-owner.webp)

## 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。[速率限制文档](https://platform.claude.com/docs/en/api/rate-limits)列出了这些情况和对应的响应头。

下一次请求要更小、更慢、更可测。按 retry-after 等待，减少并发，缩短实际输出（输出 token 桶按实际生成量计，max_tokens 本身不占额度），把大任务拆开，缓存稳定上下文，然后只在同一模型、同一凭证、同一路由上重试一个请求。

![Anthropic直连API的临时429按header限速，而强制月度支出上限须等待或申请提高](https://blog.laozhang.ai/posts/zh/claude-rate-exceeded-error/img/explainer-2.webp)

## Claude Code：先查 active route

Claude Code 多了一层路由。/status 会告诉你当前认证路径；ANTHROPIC_API_KEY 会让请求走 API key workspace。不要用订阅升级去修 API-key 429，也不要用 API header 去解释订阅 session window。计费和权限归属可参考 [Claude Code API Key 和订阅计费怎么选](https://blog.laozhang.ai/zh/posts/claude-code-api-key-vs-subscription-billing)，配置边界见 [Claude Code API 配置：先选路由，再设置 Key、模型和网关](https://blog.laozhang.ai/zh/posts/claude-code-api-configuration)。

## 为什么用量看起来还够，请求却被挡

直连 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？

同路验证仍失败且证据包完整时再联系对应归属方。

## 参考来源

本文引用的外部页面，按正文出现顺序排列。最后更新于 2026-10-05。

- [Claude Code 的错误说明](https://code.claude.com/docs/en/errors) (code.claude.com)
- [更新日志](https://raw.githubusercontent.com/anthropics/claude-code/main/CHANGELOG.md) (raw.githubusercontent.com)
- [速率限制文档](https://platform.claude.com/docs/en/api/rate-limits) (platform.claude.com)