--- title: "解决 Claude overloaded 529 错误和 rate limit 429 错误" description: "529 overloaded_error 表示 Claude API 对所有人都处于繁忙状态。429 rate_limit_error 表示你的组织触发了限制。两种错误都应使用退避策略重试。" canonical: "https://logbrew.co/zh-Hans/guides/claude-overloaded-rate-limit-error" last_updated: "2026-11-10" --- # 解决 Claude overloaded 529 错误和 rate limit 429 错误 529 `overloaded_error` 表示 Claude API 对所有人都处于繁忙状态。429 `rate_limit_error` 表示你的组织触发了限制。两种错误都应使用退避策略重试。 2026年11月10日 用 Claude Code 2.1.319和@anthropic-ai/sdk 1.7.0 实测 作者 [Furkan Erday](https://github.com/furkanerday). Furkan Erday 是 LogBrew 的创始人，每天用 Claude Code 和 Codex 开发 LogBrew。 Canonical: https://logbrew.co/zh-Hans/guides/claude-overloaded-rate-limit-error ## 各客户端每次重试前等了多久 | | 每次重试前等待的秒数 | 重试次数 | 总用时 | | --- | --- | --- | --- | | Claude Code，每次都返回 529 | 0.6 · 1.1 | 2 | 2.4 秒 | | Claude Code，每次都返回 429 | 0.5 · 1.2 · 2.5 · 4.1 · 8.8 · 18.8 · 34.2 · 35.4 · 36 · 39.9 | 10 | 182 秒 | | 设置 `maxRetries: 5` 的 TypeScript SDK，每次都返回 529 | 0.4 · 1 · 1.9 · 3.5 · 7.4 | 5 | 14.3 秒 | ## 在 Claude Code 中解决 ### 查看 Claude 状态页 如果 status.claude.com 上有容量相关的公告，说明问题出在 Anthropic 一侧，只能等待恢复。 ### 稍等后重试 `API Error: Repeated 529 Overloaded errors` 表示 Claude Code 已经重试过了。529 不会计入你的用量限制。 ### 切换到其他模型 Anthropic 按模型分别统计容量。换一个模型，例如 Opus 繁忙时改用 Sonnet。 ```bash /model ``` ### 为脚本设置备用模型 在 print 模式下，`--fallback-model` 会在多次出现 529 错误后切换到第二个模型。我们测试时，它在 3 个请求后切换。 ```bash claude -p "Run the tests" --fallback-model sonnet ``` ### 让无人值守的任务继续运行 在 CI 等无人值守的运行中，这个设置会持续重试 529 和 429 错误，直到容量恢复。 ```bash export CLAUDE_CODE_RETRY_WATCHDOG=1 ``` ## 在你自己的应用中解决 ### 使用退避策略重试 官方 Claude SDK 默认对 429、529 和其他 5xx 错误重试 2 次，采用指数退避，并遵循 `retry-after` 响应头。如果你的应用可以等更久，调大 `maxRetries`。 ```bash import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic({ maxRetries: 5 }); ``` ### 记录错误及其请求 ID 重试次数用完后，SDK 会抛出 `OverloadedError` 或 `RateLimitError`。保存 `error.requestID`，方便 Anthropic 支持团队查找这个请求。 ```bash try { await client.messages.create(request); } catch (error) { if ( error instanceof Anthropic.OverloadedError || error instanceof Anthropic.RateLimitError ) { console.warn("Claude API busy", error.status, error.requestID); } throw error; } ``` ### 逐步增加流量 你自己的流量突然激增，可能触发 429 加速限制。逐步增加流量，并保持平稳。 ## 我们实测看到的结果 真实的 529 无法人为触发，所以我们让 Claude Code 和 TypeScript SDK 连接一个本地测试服务器，它对每个请求都返回 529 或 429。Claude Code 会把这类服务器当作网关，所以在真实 API 上的会话可能表现不同。 Claude Code 发送了 3 个请求，都收到 529，然后在 2.4 秒后停止，并显示 `Repeated 529 Overloaded errors`。加上 `--fallback-model sonnet` 后，它在这 3 个请求之后切换到 Sonnet，又在大约 3 分钟内重试了 10 次。遇到 429 时，它在 182 秒内重试了 10 次，等待时间从 0.5 秒逐步增加到 40 秒，最后显示 `Request rejected (429)`。设置 `CLAUDE_CODE_RETRY_WATCHDOG=1` 后，我们在 150 秒后停止运行时，Claude Code 仍在重试 529。 在默认设置下，SDK 共发送 3 个请求，即首次请求加 2 次重试，1.3 秒后抛出 `OverloadedError`。设置 `maxRetries: 5` 后，它在 14.3 秒内发送了 6 个请求。当 429 带有 `retry-after: 3` 时，SDK 每次重试前都等待 3 秒，Claude Code 在前 3 次重试前也各等待 3 秒。 ## 529 和 429 是不同的错误 529 `overloaded_error` 表示 API 对所有用户都处于繁忙状态。这不是你的限制，也不会计入你的配额。 429 `rate_limit_error` 与你的组织有关。你触发了速率限制、用量等级的每月消费上限，或 Claude Code 工作区的消费限制。因消费上限产生的 429 不带 `retry-after` 响应头，并会一直失败，直到访问恢复，所以这时重试没有用。 ## Claude Code 套餐限制不是 API 错误 `You've hit your session limit` 和 `You've hit your weekly limit` 来自你的 Claude 套餐。会话限制就是大家常说的 5 小时限制，是一个滚动时间窗口。运行 `/usage` 可以查看这两项限制及其重置时间。 `Server is temporarily limiting requests (not your usage limit)` 是服务器端的短时限流，Claude Code 会自动重试。`Request rejected (429)` 表示某个 API 密钥、Amazon Bedrock 项目或 Google Cloud 项目触发了它自己的速率限制。 Shell 中的 `ANTHROPIC_API_KEY` 优先于你的套餐，所以 Claude Code 可能会触发这个密钥较低的限制。运行 `/status` 查看当前使用的是哪种登录方式。 #16157 有 1,499 条评论，反馈 Max 用户几乎一开始就触发了限制。2026 年 1 月，一位 Anthropic 工程师表示，团队还没有合理的解释。#29579 反馈在用量只有 16% 时就出现 `Rate limit reached`，#6457 反馈不到 90 分钟就触发了 5 小时限制。这 3 个反馈目前都仍未关闭。 ## 常见问题 ### 529 错误会计入我的 Claude 用量限制吗？ 不会。Claude Code 文档说明，529 不是你的用量限制，也不会计入你的配额。 ### Claude overloaded 错误会持续多久？ Anthropic 表示这通常是暂时的。在 status.claude.com 查看是否有未结束的事件及其最新进展。 ### Claude Code 为什么提示 rate limit reached？ 可能是你的套餐额度用完了，服务器短时限流，或者某个 API 密钥触发了速率限制。`/usage` 和 `/status` 可以告诉你是哪一种。 ### Claude Code 的限制什么时候重置？ 提示信息会写明时间，例如 `resets 3:45pm`。`/usage` 也会显示。 ### 我的应用应该重试 529 错误吗？ 应该，并使用指数退避。官方 SDK 默认重试 2 次。在我们的测试中，TypeScript SDK 的等待时间与 `retry-after` 要求的完全一致。 ## 查看应用中的每个 Claude API 错误 如果你的应用调用 Claude API，LogBrew 会把重复的 529 和 429 错误聚合成 1 个问题，并显示每个问题出现的频率。免费额度充足，无需绑卡。 [免费开始](https://logbrew.co/zh-Hans) ## 参考来源 - [Claude API docs, Errors](https://platform.claude.com/docs/en/api/errors) - [Claude API docs, Rate limits](https://platform.claude.com/docs/en/api/rate-limits) - [Claude Code docs, Error reference](https://code.claude.com/docs/en/errors) - [anthropics/claude-code#16157](https://github.com/anthropics/claude-code/issues/16157) - [anthropics/claude-code#29579](https://github.com/anthropics/claude-code/issues/29579) - [anthropics/claude-code#6457](https://github.com/anthropics/claude-code/issues/6457) ## 更多 AI 编程智能体指南 - [在 Claude Code 和 Codex 中添加 MCP 服务器](https://logbrew.co/zh-Hans/guides/mcp-server-claude-code-codex) - [在 Claude Code 和 Codex 中使用 AGENTS.md](https://logbrew.co/zh-Hans/guides/agents-md) - [修复 Claude Code、Codex 和浏览器 JavaScript 中的错误](https://logbrew.co/zh-Hans/guides)