Claude Code Agent Loop 研究系列（07）—— 重试与错误恢复：8 层恢复叠加
内容提要
本文介绍Claude Code在AI循环中处理基础设施错误（网络故障、限流、超载等）的8层恢复机制。核心策略包括：通过withRetry包装器最多重试10次，优先遵循服务端的x-should-retry和Retry-After头信息，对529超载错误区分前台后台任务，主模型失败时切换备用模型，以及针对prompt_too_long和max_tokens错误实施三级恢复。整体设计强调让循环尽可能自愈，仅在无法恢复时才向用户暴露错误。
延伸解读
服务端主导的重试决策
Claude Code 的重试策略并非客户端自行判断，而是优先遵循服务端返回的 x-should-retry 和 Retry-After 头。这种设计让服务端能根据集群状态动态调整重试语义，客户端只需在头缺失时兜底。对开发者而言，这提示在构建分布式系统时，将重试决策权交给服务端可避免客户端启发式规则的误判，同时减少客户端发版频率。
避免重试雪崩的 529 处理
面对 529 超载错误，Claude Code 区分前台与后台任务：后台任务立即失败，前台任务才重试且设上限。这避免了盲目重试加剧集群压力，体现了生产环境对请求优先级的精细管理。开发者可借鉴此思路，在系统过载时优先保障用户直接等待的请求，牺牲非关键任务以维持整体稳定性。
模型切换的细节考量
主模型失败后切换备用模型时，Claude Code 不增加 turn 计数，并剥离 thinking signature 以保证兼容。这确保用户的一次交互不被内部恢复消耗，同时避免因模型差异导致请求被拒。对于多模型架构，这提示在切换时需考虑消息格式的兼容性，并保护用户可感知的交互次数。
多级恢复的容错哲学
无论是 prompt_too_long 还是 max_tokens 错误，Claude Code 都采用三级恢复策略，从激进压缩到注入提示，最后才抛给用户。这种设计将错误对调用方隐藏，直到所有恢复手段耗尽。它体现了“循环作为恢复引擎”的理念，优先自愈，减少用户干预，但同时也需注意过度隐藏可能延迟问题暴露，需在恢复与透明间平衡。
Q&A
Claude Code 在调用 API 时如何处理网络错误和限流？
Claude Code 每次调用 LLM 都通过 withRetry 包装器，默认最多重试 10 次（可用环境变量 CLAUDE_CODE_MAX_RETRIES 覆盖）。重试前会优先参考服务端返回的 x-should-retry 头判断是否可重试，若头缺失则根据状态码和错误类型进行启发式判断。退避策略优先使用 Retry-After 头指定的时间，否则采用指数退避（1s、2s、4s...）。
Claude Code 如何处理 529 超载错误？
对于 529 超载错误，Claude Code 区分前台和后台任务：后台任务（如 compact、session_memory 查询）立即失败不重试，以避免加重集群压力；前台任务（用户正在等待的）会重试，但有上限（MAX_529_RETRIES），达到上限后抛出 FallbackTriggeredError 触发模型切换。
Claude Code 在主模型失败时如何切换备用模型？
当主模型连续失败达到上限（如 529 重试上限）时，Claude Code 会捕获 FallbackTriggeredError，并尝试切换到备用模型（如从 claude-opus-4-6 切换到 claude-sonnet-4-6），使用相同的 messages 数组重新发送请求。切换时不会增加 turnCount，且会剥离消息中的 thinking signature 块，因为不同模型的 signature 不兼容。
Claude Code 如何处理 prompt_too_long 错误？
Claude Code 对 prompt_too_long 错误实施三级恢复：第一级是 Context collapse drain，激进压缩老消息；第二级是 Reactive compact，即被动触发标准压缩流程；第三级是抛给用户，显示明确错误。前两级恢复期间错误对 SDK 调用方隐藏，只有三级都失败才暴露。
Claude Code 对 max_tokens 错误有哪些恢复措施？
Claude Code 对 max_tokens 错误提供三次恢复机会：第一次上调 max_tokens 上限并重发；第二次注入一条 '[Output token limit hit, continue]' 用户消息，让模型继续生成；第三次仍失败则放弃并抛给用户。恢复上限为 MAX_OUTPUT_TOKENS_RECOVERY_LIMIT = 3。
Claude Code 的 8 层恢复机制具体包括哪些层次？
8 层恢复机制从近到远包括：1. withRetry 内的指数退避重试（最多 10 次）；2. withRetry 外的 fallback model swap（换模型重试）；3. 换模型时剥离 signature 块；4. prompt_too_long 三级压缩恢复（collapse → compact → 抛出）；5. max_tokens 三级恢复（escalate → 注入 continue → 抛出）；6. reactive_compact / stop_hook / max_output 等 transition；7. maxTurns 硬保险；8. 错误 withhold 到 SDK 层，只暴露最终无法恢复的错误。
