正在打开页面…
正在加载内容，请稍候。
报错排查 / Claude Code
Claude Code API Error 429：限流、用量上限与退避
Claude Code API Error 429 先看错误正文和响应头，区分请求速率、token 速率、用量上限与网关限制。暂停重复任务，保留请求 ID；临时限流按返回信息退避，用量上限则处理额度或等待明确恢复时间。
全球顶尖大模型 · 一站式接入
先定位失败阶段按看到的错误，选择下一步
API Error 429
可能附带：rate_limit_error、retry-after、request-id
错误正文与响应头决定下一步- 先看来源：CLI 用 /status 核对认证和网关地址；订阅登录、官方 API Key 与第三方网关是不同额度。VS Code、桌面端另核对各自配置来源。
- 有 retry-after：按返回等待值处理，并检查 anthropic-ratelimit-requests/input-tokens/output-tokens 的 remaining 与 reset（若实际返回）。它们说明受限维度，不等于付费余额。
- 没有 retry-after：不能直接猜“等 30 秒”。官方 Messages 若附 error.details.error_code=enforced_spend_limit_reached，应处理消费上限；其他服务按脱敏正文与控制台规则判断。
- HTTP 200 但输出中断：保留流式错误和已完成工具步骤，确认是否写过文件，再决定继续；不要把整个任务立即重复提交。
先区分配置、响应与重试
配置与检查示例
本站绘制的内容说明图：对照本页「API Error 429」与配置要点；图中均为正文示例，不含有效 Key，也不是修复成功截图。
本站绘制的内容说明图：只对应本页错误的现象、检查与恢复条件；复测需要保留原客户端、时间、模型和脱敏响应，未执行项目不标成功。
先按顺序处理
- 停止同一 Key 的重复终端和自动重试，保留错误体、状态码、时间与请求 ID。
- 核对认证来源、目标型号、令牌分组和限制，避免因 429 同时修改 Key、模型与地址。
- 临时限流按 retry-after 等待；无明确等待值时使用有上限的指数退避与随机延迟，持续失败就停。
- 消费上限先处理额度或等待明确恢复时间；一次只恢复一个任务，短请求通过后再恢复原任务。
先减少正在发起的请求
收拢并行任务和自动代理。长上下文会消耗更多输入 token；缩小一次任务涉及的文件和重复材料。切模型之前核对授权、接口和输出差异，不把切换当作解除所有限制的保证。
让一个层级负责重试
确认客户端或 SDK 是否已经重试，避免外层脚本再次循环。retry-after 存在时优先遵守；缺失时可从短等待逐步增加并加入随机延迟，设置最大次数与总等待时间。没有明确恢复条件的额度错误应直接停止。
把可排查的信息保存下来
保留状态码、error.type/message、请求 ID、retry-after 和实际返回的 ratelimit 头。网关没有这些头时，用同一时间的控制台日志补充，不凭空推断上游。截图或日志分享前删除 Key、认证头和业务正文。
配置与检查示例
先备份并合并到对应配置，不覆盖原文件。真实 Key 留在本地；型号 ID 与协议从当前目录核对。
export ANTHROPIC_BASE_URL=https://api.apizt.com
export ANTHROPIC_AUTH_TOKEN="$tokenba_API_KEY"
claude --version
# 进入 CLI 后用 /status 核对来源
# 目标模型从当前分组目录复制，并确认 Messages 支持怎样才算修好了
- 来源明确：知道请求使用订阅、官方 API 还是网关，而不是只看到了 429。
- 等待条件明确：记录 retry-after 或正文要求；消费上限不会因短暂退避自动消失。
- 单个最小请求返回有效文本，再核对同次请求日志。真实请求可能产生费用，本页未替你执行。
- 回到测试仓库，检查读取、修改及测试结果；记录中途失败、重试与全部用量，再决定恢复并发。
核对日期：2026-10-07。依据 Claude 官方 API 限流、错误与 Claude Code 网关文档。官方 API 的规则不能直接当成 apizt 每个分组的规则；网关是否转发原响应头，需要看该次实际响应。本页离线故障样本不是线上 Claude Code 调用或实扣记录。
常见问题
Claude Code 429 但余额充足怎么解决？
余额与请求速率、token 速率是不同限制。查看错误正文、Retry-After 和令牌分组规则，降低并发或缩短上下文；持续失败时停止自动重试并保留记录。
Claude Code 429 没有 Retry-After 要一直重试吗？
先确认是否为临时限流。消费上限可能没有该响应头，重复重试不能修复；临时限制才使用有上限的退避和随机延迟，达到上限后停止。
429 就是余额不足吗？
不是。请求速率、token 速率和额度是不同限制。先读错误正文与响应头，再到对应平台检查。
没有 Retry-After 应该等多久？
先查原因。官方消费上限的 429 不带该头，短暂等待不能修复；确认是临时限流后才采用有限退避，持续失败就停止并保留记录。
切到 apizt 就不会 429 吗？
不能保证。第三方网关仍有令牌、分组、上游和并发限制，需按实际响应处理。
HTTP 200 能证明任务完成吗？
不能。流式可能中途报错，工具任务也可能只完成一部分。检查终态、文件变更、测试和日志。
相关步骤与官方依据
429 要保留哪些信息，才知道能否重试
下表用于阅读实际响应。2026-10-07 核对官方资料，并用本地合成故障验证临时限流和消费上限的处理分支；没有用 Claude Code 对生产模型发起请求，不把离线样本当作服务实测。
- 看到的字段
- retry-after
- 代表什么
- 服务返回的等待秒数（若存在）
- 下一步
- 先停止叠加重试，不早于该等待值重试
- 看到的字段
- requests / input-tokens / output-tokens remaining、reset
- 代表什么
- 官方 API 中受限维度的剩余量与恢复时间
- 下一步
- 根据实际返回降低请求或 token 速率；网关未转发则不猜测
- 看到的字段
- enforced_spend_limit_reached
- 代表什么
- 官方 Messages 的消费上限错误标识
- 下一步
- 处理上限或等明确恢复时间，不持续退避重试
- 看到的字段
- request-id / request_id
- 代表什么
- 关联同一次请求的排查编号
- 下一步
- 保留时间、型号、分组与脱敏正文，交给对应平台支持
- 看到的字段
- SSE error / 流式中断
- 代表什么
- 可能发生在 HTTP 200 之后
- 下一步
- 检查已完成步骤与文件，避免重复整个任务
恢复前做一次小范围验收
- 先确认限制来源与恢复条件，暂停其他任务；不要用高频短请求测试是否恢复。
- 恢复后自行发送一个最小请求，核对有效文本和日志；这一步可能收费。再在测试仓库恢复原任务，检查部分执行和失败重试。
- 离线记录仅验证合成 429 分支；真实等待时间、上游规则和任务费用仍需用自己的请求与账单核对。
核验日期与验证范围见各页记录；历史实测保留原日期，示例和空白记录表不等于真实任务结果。
2026 年 11 月 5 日补测
Claude Code 429：区分请求速率与重试时间
用本地 429 回执保留 Retry-After，检查手动重试时该记录哪些字段。
- 本地 HTTP 故障复现（固定回包）。
- 准备独立样例。安装文章所用客户端，或用 Python 3.11+ 运行标注为本地 HTTP/TOML 的样例。
- 本例操作：用本地 429 回执保留 Retry-After，检查手动重试时该记录哪些字段。
- 解压练习包，执行 python3 lab.py --output ./result u07。完整命令、样例输入和输出保存在回执。
- 打开 result/u07.json，对照实际退出码、请求路径或产物字段。
- 逐项确认下方通过条件。本例的测试范围以运行回执为准。
- 通过：记录 429 的 Retry-After 和单次恢复状态
先下载样例，再完成自己的首次调用
示例不含密钥。API 按实际用量计费；下载和点击不代表调用成功。