注册
Claude

Claude 报错 429 rate_limit_error 怎么办：速率限制、加速限制和月度花费上限三种来源，retry-after 怎么看

Claude API 返回 429 rate_limit_error，不一定是请求太快。按官方错误页和速率限制页（2026-10 查询），429 有速率限制、加速限制、触到档位月度花费上限等来源，处理办法不同。本文讲清怎么看 retry-after 和 error_code，以及 SDK 自动重试的行为。

NNathaniel bigo··原创首发·AI 辅助撰写
8 分钟读完
资料核对于 2026-10-30 · 依据官方文档与公开资料整理 免费账号 账号
本文根据 Claude 官方 API 错误页和速率限制页整理，资料核对于 2026-10-30。官方没有单独说明 claude.ai 网页版聊天里出现的 429，本文讲的是 API 返回的 429，在 Claude Code、Cursor 等工具里看到的 429 多半也是它。配图为本站整理的示意图，不是网页截图。

适用于谁

  • 调用 Claude API，返回 HTTP 429、rate_limit_error 的开发者；
  • 在 Cursor、Cline 等工具里填了自己的 Claude API Key，工具显示 429 的人；
  • 重试了很多次还是 429，想知道到底是什么限制的人。

结论先说

  1. 官方错误页对 429 的定义是：你的组织触到了速率限制，或用完了所在档位的月度花费上限，或触到了 Claude Code 工作区的花费限制。
  2. 看响应头 retry-after：有，就等那么多秒再重试，更早重试会失败；没有，且错误里带 enforced_spend_limit_reached，就是月度花费上限，重试（包括 SDK 自动重试）都会失败，直到下月 1 日 00:00 UTC 或你申请提高。
  3. 官方还提到加速限制：组织的用量突然猛增时，也可能收到 429。办法是逐步增加流量、保持稳定。
  4. 你自己设的花费上限触顶，返回的是 400（invalid_request_error）而不是 429；调高或取消限额即可。
  5. 官方 SDK 默认会对 429、5xx 和连接错误自动重试两次，指数退避，并遵守 retry-after。

429 的几种来源

图：本站根据 Claude API 错误页 和 速率限制页 整理的示意图

一、速率限制：请求太多或 token 太多

官方说明 Messages API 的速率限制按模型类别分别计算，包括：

  • RPM：每分钟请求数；
  • ITPM：每分钟输入 token 数；
  • OTPM：每分钟输出 token 数。

超过其中任何一项就会收到 429，错误信息会说明超的是哪一项。几个值得知道的细节：

  • 限制是按组织计的，换一个 API Key 不会增加额度；
  • 限制可能在很短的时间窗口里生效：官方举例，每分钟 60 个请求可能按每秒 1 个来执行，所以突发的并发请求也会触发；
  • 官方用令牌桶算法，容量是持续补充的，不是整点重置；
  • 对大多数模型，命中缓存读取的输入 token 不计入 ITPM，所以用好提示词缓存能提高实际吞吐，缓存方法见 /guides/claude-prompt-caching；
  • max_tokens 不影响 OTPM 的计算，OTPM 按实际生成的 token 数算。

响应头里会带当前限额、剩余量和重置时间，名字以 anthropic-ratelimit- 开头，可以按 requests、tokens、input-tokens、output-tokens 分别查看；retry-after 是还要等的秒数，官方说不是每个 429 都带它。

二、月度花费上限：重试没有用

官方规则：Start、Build、Scale 三档都有月度花费上限。用到上限后，API 用量暂停到下月 1 日 00:00 UTC，期间请求返回 429。

和普通速率限制的区别：

  • 错误类型同样是 rate_limit_error；
  • 没有 retry-after 头；
  • 消息里写着月度用量阈值并给出恢复时间，error.details.error_code 是 enforced_spend_limit_reached；
  • 升到更高档位可以恢复，提高上限在控制台的速率限制页发起「Request tier increase」。

具体的档位上限金额，请看官方页面当天的数字，本文不引用。

自己设置的上限不一样：在控制台账单页设置的花费上限触顶时，请求返回 400，消息以「You have reached your specified API usage limits」开头，调高或移除限额就能恢复。API Key 和控制台的使用见 /guides/claude-api-key-console。

三、加速限制：用量突然猛增

官方在错误页和速率限制页都提醒：如果组织的用量突然大幅上升，可能因为加速限制收到 429。避免的办法是逐步增加流量，保持稳定的使用节奏，比如批量任务从低并发开始慢慢加。官方没有给出加速限制的具体阈值。

四、对照表：收到 429 先这样查

收到 429 先这样查

图：本站根据 Claude API 速率限制页 整理的示意图

五、要更高的额度怎么办

官方提供的途径：

  1. 控制台「Rate limits」页里的 Request tier increase，可申请更高的速率限制或月度花费上限；
  2. 联系 Anthropic 支持，紧急情况也可以走这里；
  3. 用工作区（Workspace）给不同项目设置更低的限额，避免某个项目占满整个组织的额度。官方说明默认工作区不能设花费上限；
  4. 在控制台的 Usage 页可以看到速率限制的图表，了解自己的峰值和缓存命中率。

常见问题

Q：我已经等了很久还是 429，为什么？

先看是不是花费上限：没有 retry-after 且 error_code 是 enforced_spend_limit_reached，那就不是等几十秒的问题，要等到下月初或申请提高。

Q：429 和 529 有什么区别？

429 是你所在组织的限制，529 是 API 整体过载，见 /guides/claude-api-error-529-overloaded。

Q：Claude Code 里的报错怎么看？

常见报错见 /guides/claude-code-common-errors；订阅额度不是 API 额度，两者区别见 /guides/claude-subscription-vs-api。需要 Claude 订阅的话，本站有 Claude Pro 充值页。

Q：怎么确认是官方故障？

看 /guides/claude-down-check-status-page。

参考资料

  • Claude API 错误 — https://platform.claude.com/docs/en/api/errors
  • Claude API 速率限制 — https://platform.claude.com/docs/en/api/rate-limits

Nathaniel 的更多内容

  1. 01

    Microsoft Copilot 官网入口在哪、怎么下载：网页版、Windows 应用、手机应用和工作账号入口怎么选

    Microsoft Copilot 有网页版、Windows 应用、手机应用，工作或学校账号还有单独入口。本文按微软支持页面讲清各入口、各自支持的登录账号、Windows 应用从 Microsoft Store 下载，以及怎么区分微软的 Copilot 和 GitHub Copilot。

    其他 AI 工具0
  2. 02

    GitHub Copilot 提示无法连接到服务怎么办：could not connect to server、ETIMEDOUT、证书错误的官方排查办法

    Copilot 提示 could not connect to server、read ETIMEDOUT 或证书错误，多与代理、防火墙有关。本文按 GitHub 官方网络错误排查文档，讲 curl 测连通性、代理与认证限制、证书错误处理和公司网络放行清单。

    GitHub Copilot0
  3. 03

    GitHub Copilot 报错「Language model unavailable」怎么办：VS Code 团队说的头号原因，以及怎么收集诊断信息

    VS Code 里 Copilot Chat 提示 Language model unavailable，官方没有单独说明。本文按 VS Code 团队的说法讲头号原因（公司防火墙没放行新端点）、怎么看 Failed to fetch models、运行 Chat Diagnostics。

    GitHub Copilot0
  4. 04

    Windows 里的 Copilot 是什么软件、能卸载吗、怎么关闭：卸载路径、Copilot 键和 Win+C 的处理，公司电脑怎么管

    Windows 11 新电脑上的 Copilot 是微软的 AI 助手应用，可以卸载。本文按微软官方文档讲清它是什么、卸载路径、不想被 Copilot 键或 Win+C 唤起怎么改、卸载后怎么装回来，以及公司电脑上 IT 管理员的 AppLocker 和 PowerShell 做法。

    其他 AI 工具0
  5. 05

    Cursor 报错「User is unauthorized」怎么办：官方员工给的排查顺序，以及怎么取到 Request ID 反馈

    Cursor 里发消息时提示 User is unauthorized，官方帮助中心没有单独说明。本文整理官方论坛里员工的回复：先检查有没有自定义 Base URL、退出重新登录并完全重启，仍不行就用 Report AI Action 取新的 Request ID 反馈；邮箱域名被拦截的情况官方怎么说。

    Cursor0
  6. 06

    Cursor 登录提示「Can't verify the user is human」怎么办：人机验证失败的常见原因，以及登录域名迁移后的放行清单

    Cursor 登录时提示无法验证用户为真人，官方帮助中心没有这条报错的专门说明。本文整理官方论坛里反馈的常见情形（拦截人机验证请求、密码管理器自动点继续、换浏览器），并按官方帮助页说明 Cursor 登录页正迁移到 accounts.spacex.ai 与 accounts.x.ai，公司网络需要放行。

    Cursor0

同产品的其他教程

  1. 01

    Claude Code 官网下载在哪、怎么安装：原生安装、npm、Homebrew、WinGet 怎么选，Windows 要不要装 Git

    搜「Claude Code 官网下载」「为什么要装 Git」「为什么不推荐 npm」，官方文档的答案是：安装说明在 code.claude.com，原生安装标为推荐，npm 要 Node.js 22，Windows 的 Git 是可选的。本文按官方文档逐项说明。

    Claude0
  2. 02

    Claude Code 无法粘贴、无法读取图片怎么办：Ctrl+V 和 Alt+V 的区别，拖放和路径三种放图方法

    Claude Code 里粘贴不了截图、读不到图片？官方文档给了三种把图放进对话的方法：拖放进窗口、Ctrl+V 粘贴（Windows 和 WSL 用 Alt+V）、直接写图片路径。官方没有为「粘贴失败」单列排查，本文把官方写明的做法和通用排查分开讲。

    Claude0
  3. 03

    Claude 报错 529 overloaded_error 怎么办：API 暂时过载是什么意思，和 429、500、504 怎么区分

    Claude API 返回 529 overloaded_error，官方的解释是 API 暂时过载，全体用户高峰时都可能遇到，不是你的 Key 或余额出了问题。本文按官方错误页（2026-10 查询）讲清它和 429、500、504 的区别、SDK 怎么自动重试、流式请求中途报错怎么处理。

    Claude0
  4. 04

    Claude 收费吗：免费版能用什么，Pro、Max、Team 官方标价是多少（2026 年 10 月官方定价页）

    Claude 收费吗？官方有免费套餐，也有付费套餐。按官方定价页（2026-10 查询）：Pro 年付折合 17 美元每月、月付 20 美元，Max 从 100 美元每月起，Team 标准席位年付 20 美元。本文讲清各档标价、税费、手机端价格差异，以及订阅不含 API。

    Claude0
  5. 05

    Claude 官网入口在哪、有没有中文版：claude.ai 和 claude.com 分别是什么，怎么认出假冒网站

    搜「Claude 官网入口」「Claude 官网中文版」，先分清 claude.com 是官方站点、claude.ai 是网页版登录入口。官方界面语言列表里没有简体中文，但可以直接用中文对话。本文列出官方入口、下载页和帮助中心，并说明怎么辨别仿冒站。

    Claude0
  6. 06

    Claude 登录报错对照（账号被停用以外）：There was an error logging you in、收不到登录邮件、验证码、Google 登录的处理

    Claude 登录不上，除了账号被停用，还有登录出错、收不到登录邮件、在另一台设备点链接、想设密码、Google 登录异常等情况。本文按官方登录帮助整理各提示的原文和处理，账号被停用另见专门文章。

    Claude0

0 条评论

登录 后参与评论

还没有评论，来抢沙发～