Hello，Lena 来了。去年有段时间，我盯着一个跑了两周都很正常的 workflow，然后它突然就……停了。没有有用的 error，没有明显原因。任务完成了 80%，agent 就这么安静了下来。
接下来几个小时，我一直以为是自己的代码有问题。并不是。那是一个 Claude usage limit（使用限制）——但不是我以为会触发的那个。
这段经历让我开始思考。之前看到的大多数 troubleshooting 都把"Claude 挂了"当作一个单一问题来处理。但翻着日志，我逐渐注意到三种完全不同的状况被混为一谈了。而一旦我能区分它们，修复方案就变得清晰多了。
这就是那份拆解——我希望自己在开始之前就拥有的那份。
当 Claude 触发限制或宕机时，到底发生了什么
第一件值得慢下来想清楚的事：并非所有 Claude 故障都是同一种故障。
Rate Limits（速率限制） vs Usage Caps（用量上限） vs Outages（服务中断）
这是三种不同的问题，有着不同的成因、不同的错误特征和不同的修复方式。搞混它们会浪费时间。
Rate limits（速率限制） 是对请求和 token 的每分钟约束。你的 rate limit 取决于你所在的 usage tier（使用层级），通过三个关键指标来衡量：requests per minute (RPM)、tokens per minute (TPM)，有时还有 daily token quotas（每日 token 配额）。当你超出这些限制时，你会收到一个 HTTP 429 Too Many Requests。这是一个 throughput（吞吐量）问题——你在一个短时间窗口内请求得太多、太快了。
Usage caps（用量上限） 则不同。Claude Code rate limits 作为一个由三个独立、重叠的约束组成的系统运行，而 dashboard 上显示的百分比只反映了其中一个。你可能看着 Anthropic console 显示日用量还剩 6%，以为一切都好，结果仍然撞了墙——因为你消耗完的是 per-minute token ceiling（每分钟 token 上限），而不是 daily 那个。这是一个微妙但重要的区别。
Outages（服务中断） 是完全不同的另一类。529 Service Unavailable 意味着 Anthropic 的服务器在系统层面承受了压力。529 error 不是你的问题——它发生在 Anthropic 的服务器承受跨所有用户的高流量时，而被拒绝的 529 请求不会计入你的账单。你无法通过代码优化来修复 529。你等待，你 back off（退避），你检查 Anthropic 状态页 获取 incident 更新。
这个区分为什么如此重要：错误的诊断会导向错误的修复。我见过有人升级他们的 API tier 来修复实际上只是一个 transient outage（瞬时中断）。也见过有人耐心等待一个 429 "自行恢复"，而他们真正需要的是换一种请求模式。
每种故障模式如何影响 Agent 工作流
Chat interface 在 Claude 碰到限制时还算宽容。你看到一条消息，等一等，再试一次。
Agent workflows 可不宽容。Claude Code 并不是向 API 发送一个 prompt 然后等待响应——每次交互都是一段 multi-turn conversation（多轮对话），包含 system prompt、累积的对话历史、拉入 context 的文件内容，以及 tool-use tokens。一个看似简单的"编辑这个文件"命令，在完整 context 组装后，可能在单次 API call 中消耗 50,000–150,000 tokens。
Rate limit hit 在这种环境中会引发 retry loops（重试循环）——agent 不断发送请求，每一个都失败，每一个都在消耗计入你 quota 的 tokens。Usage cap hit 可能在任务执行到一半时中断执行，有时还没有明确信号表明这是一个 cap 问题。而 outages 则造成我称之为 silent failures（静默失败）的现象：tool call 挂起、超时，取决于你的设置，可能不会记录任何有用信息。
这就是我在那个卡住的 workflow 上花了不舒服的几个小时的原因。Agent 触发了 rate limit，进入了一个没有 backoff 的 retry loop，在我注意到之前就烧完了我剩余的 token budget。
针对每种故障模式的即时修复
Rate Limit Hit：先止血
最有效的即时修复方案是 exponential backoff with jitter（指数退避加抖动）。原理是：每次 retry 等待的时间是上一次的两倍，加上一个小的随机偏移量（jitter），用来分散来自多个 client 的 burst retries（突发重试）。
Jitter 这部分很容易被忽略，但它很重要。没有它的话，当多个 worker 或并行的 agent thread 同时触发了同一个 rate limit，然后全部在完全相同的间隔后重试，你就在每个 retry cycle 重新制造了 burst 问题。你不是在解决问题——你只是把它推迟了一个固定偏移。
一个简单的 Python 模式，一直很好用：
import time, random
from anthropic import Anthropic, RateLimitError
def call_with_backoff(client, messages, max_retries=5):
for attempt in range(max_retries):
try:
return client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
messages=messages
)
except RateLimitError as e:
if attempt == max_retries - 1:
raise
base_wait = min(2 ** attempt, 60)
wait_time = base_wait + (random.random() * base_wait * 0.1)
time.sleep(wait_time)
值得一提：Anthropic 官方 Python SDK 默认包含内置的 retry logic。它会对 429 错误自动重试最多 2 次，使用 exponential backoff。对于生产环境中容错要求更高的 agent workflows，你通常需要配置更高的 max_retries 值并加入你自己的 jitter 逻辑。
除了 retry 之外，降低并行度。如果你有 5 个 agent threads 同时发起 Claude API calls，而你的 rate limit 是 50 RPM 且共享 token pool，你几乎肯定会碰撞。错开请求、尽可能 batch，不要假设并行执行能线性提升 throughput。
Usage Cap Hit：不要从零重来
任务执行到一半碰到 cap 是最让人抓狂的故障模式之一，因为在 cap hit 之前完成的工作通常仍然有效。修复方案不是重启——而是保存状态然后恢复。
如果你在 subscription plan 上，并且在生产 workflows 中频繁碰到 caps，Batch API 允许异步处理大量请求，在 input 和 output tokens 上都有 50% 折扣——对于对延迟不敏感的任务，这能显著扩展你的有效容量。如果你有较大的 system prompt 或重复的 context，Prompt caching 值得实现：cached tokens 的费用只是标准 input tokens 的一小部分，在长时间的 agent session 中，相同 context 被反复发送，这笔节省会迅速累积。
如果 usage cap 是结构性的不匹配——你确实需要比当前 tier 更多的 throughput——在做升级决定之前，请到 docs.anthropic.com/en/api/rate-limits 核实当前的 plan limits，因为这些数字会在不通知的情况下变化。
Outage 处理：优雅降级
对于 outages，核心模式是 circuit breakers（熔断器）和 graceful degradation（优雅降级）。
Circuit breaker 模式有三种状态：Closed（正常运行）、Open（检测到故障——停止尝试）和 Half-Open（测试服务是否已恢复）。应用到 Claude API 集成中：在连续 N 次失败后，circuit 打开并停止发送请求。经过一段 timeout period 后，它允许发送一个 probe request（探测请求）。如果成功，circuit 再次关闭。
和 retry 的关键行为差异在于：retries 处理单个请求失败，circuit breakers 处理系统性故障。如果 Claude 宕机 20 分钟，你不希望你的 agent 在这段窗口内发出 400 个失败的 API calls。你希望它检测到这个模式，停止尝试，排队等待，并在服务恢复后继续。
为你的 Agent 工作流构建弹性
这些模式才是有意思的部分——至少对我来说是。上面的即时修复能止住血。这一节要讲的是如何一开始就不流血。
Fallback Model Routing（备选模型路由）
当 Claude 不可用时，拥有一个 fallback model endpoint 意味着你的 agent 可以在功能降级的情况下继续运行，而非完全停摆。实际做法是这样的：你的主 workflow 路由到 Claude；如果你收到一个 529 或 circuit breaker 触发，你把低风险的子任务路由到一个 secondary model，而 critical-path 的工作排队等 Claude 恢复。
这不是简单的即插即用——不同模型有不同的 tool call 行为、context 格式和输出一致性。我的建议是从窄范围的 fallback 开始：找出你的 agent workflow 中真正与模型无关的部分（summarization、simple classification、format conversion），先把这些路由到 fallback。把复杂推理和 tool-heavy 的步骤留在队列里。
关于 multi-provider routing 和完善的 fallback 逻辑，Portkey 的 LLM gateway 详细介绍了相关模式——retries、fallbacks 和 circuit breakers 作为分层系统的组合方式，如果你要为生产可靠性而构建，非常值得一读。
Checkpoint and Resume Patterns（检查点与恢复模式）
说实话，这部分我还没有完全想清楚。但方向是明确的：agent state 需要在 task boundaries（任务边界）处是可序列化的。
基本做法：在发起 Claude API call 之前，把你当前的 agent state——任务进度、已完成步骤、中间输出——序列化到持久化存储中。如果调用失败且 circuit breaker 打开，你就有了一个 checkpoint 来恢复，而不是从头开始。
更难的部分是在步骤之间存在依赖的 agentic workflows 中定义"task boundaries"。我发现最干净的方法是把每次 tool call 都当作一个潜在的 checkpoint，即使这感觉粒度太细。合并 checkpoints 比拆解一个没有恢复点的、部分完成的多步骤任务要容易得多。
分离关键路径与后台任务
并非所有 agent task 都需要同样的可用性保证。后台任务——日志记录、摘要生成、低优先级分析——可以承受 Claude 数分钟甚至数小时不可用。 关键路径任务不行。
显式地建模这一点，让你能为不同场景设计不同的弹性策略：关键路径获得积极的 retry 逻辑、fallback models 和 circuit breaker 监控；后台任务被耐心排队，不承受 retry 压力。单凭这一点就能显著降低 Claude usage limits 带来的噪声，因为你不再把每一个失败的 API call 都视为同等紧急。
更深层的问题：每个 Workaround 都在被重新发明
有件事一直困扰着我。
我和足够多正在构建 Claude-based workflows 的人交流后，注意到了一个模式。有人解决了 exponential backoff 的问题。他们实现得很好。它能跑。然后三个月后，一个队友启动了新项目，碰到了同样的 429 errors，然后再次解决了它——稍微不同的方式，稍微不同的文件，稍微不同的做法。第一个解决方案从来没有传递过去。
Checkpoint patterns、circuit breaker configurations、fallback routing logic 也是如此。一个全局的 retry counter 把所有 tools 当作单一故障域来处理——当一个 tool 降级时，它耗尽了所有其他 tool 的 budget。有人发现了这个问题，构建了 per-tool circuit breakers，然后它就留在了一个项目的 codebase 里，没有文档，也没有被下一个遇到完全相同问题的项目所参考。
这不是一个代码问题——这是一个 knowledge structure（知识结构）问题。一个经过验证的 fallback strategy 应该以可复用的形式存在，跟随 agent capability 一起传递，而不是留在一段聊天记录或某个被遗忘的一次性脚本里。
对此我还没有一个完整的答案。我一直在思考。
FAQ
Claude 目前对 API 用户的 rate limits 是多少？
这些数字会变化，所以在做架构决策之前请查阅官方 Anthropic rate limits 文档。大致参考：limits 基于 tier（Tier 1 到 Tier 4），以 RPM、ITPM 和 OTPM 来衡量，更高的 tier 在达到消费门槛后解锁。Tier 1 起步保守；Tier 4 慷慨许多。2025 年文章中的数字现在可能已经过时了。
如何在生产 agent workflow 中处理 Claude outages？
Circuit breakers 是正确的模式。在连续失败达到阈值后打开 circuit，在 open 状态下排队等待，超时后探测，服务恢复后关闭。在你的监控中检查 status.anthropic.com 以区分局部问题和平台级别的 incident。
Claude 不可用时最佳的 fallback model 是什么？
这里没有通用答案——取决于你的 agent 在做什么。对于 structured output 任务，大多数主流模型都能处理得还不错。对于复杂的 tool-use chains 和多步推理，fallback 质量下降更为明显。先找出你 workflow 中真正与模型无关的那个窄切面，先把那部分路由到 fallback。
如何保存 agent state 使得 Claude 故障不会让任务从零重来？
在每次 Claude API call 之前，在 task boundaries 处序列化 agent state。至少包括：已完成步骤、中间输出、当前在 task graph 中的位置。粒度问题更难——倾向于更频繁的 checkpoints。存储很便宜；重跑一个两小时的 agent task 可不便宜。
如何阻止 agent 在失败的 retries 上烧 tokens？
两点：exponential backoff with jitter（让 retries 不会产生同步的 burst），以及 circuit breakers（让系统性故障不会持续消耗 retry budget）。Anthropic Python SDK 内置了基本的 retry logic——明确配置它，而不是依赖默认值。对于有并行的生产系统，加入 per-tool 或 per-operation 的 circuit breakers，这样一个降级的 endpoint 就不会耗尽你全部的 retry budget。
我可能会继续关注这个领域的发展。Limit 和 resilience patterns 感觉仍在被公开地探索和完善，我也不确定自己已经找到了适用于长时间运行 agentic workflows 的最干净版本。但三种故障模式之间的区分——至少这部分已经比较确定了。
