Claude API 超时与重试：Python、Node.js 的有限恢复策略

先判断失败是否值得重试

参数错误、认证或权限不足通常需要修复配置；短期网络故障、服务端故障或普通限流可按当前 SDK 与 API 文档有限重试。支出上限不能靠退避恢复，已发生副作用的工具操作也不能直接重放。

超时只表示客户端没有及时取得完整结果，不证明服务端没有处理。把推理请求重试与邮件、数据库写入等工具重试分开管理。记录请求 ID 和应用任务 ID，有结果不确定的步骤先查证，不能凭一条异常认定“什么都没发生”。

用 SDK 自带机制，显式写清单位

以下配置示例将单次超时设为二十秒、最多重试两次；这是教学参数，不是适合所有任务的推荐值。Python 使用秒，TypeScript 使用毫秒。示例只是定义函数，已做语法检查，未安装 SDK 或调用 API；真实环境要锁定依赖并按任务调整。

def request_summary(client, model, text):
    return client.with_options(timeout=20.0, max_retries=2).messages.create(
        model=model, max_tokens=600,
        messages=[{"role": "user", "content": "概括以下公开文本：\n" + text}],
    )

export async function requestSummary(client, model, text) {
  return client.messages.create({
    model,
    max_tokens: 600,
    messages: [{ role: "user", content: `概括以下公开文本：\n${text}` }]
  }, { timeout: 20_000, maxRetries: 2 });
}

总截止时间与熔断要在应用层考虑

单次二十秒不等于用户最多等二十秒；重试、退避和排队都会增加总耗时。应用应设置端到端期限、用户取消和并发预算，SDK 若已做重试，外层不要再套多层重试。延迟较长的合法任务可采用流式或异步任务设计，不必一律缩短超时。

原创例子：摘要页允许用户等待四十五秒，而后台有三次潜在尝试。设计时先规定总截止时间，剩余时间不足便保存失败状态并返回可恢复提示；不要让浏览器超时后后台仍无界重试。持续服务错误可暂缓新任务，稍后以少量探测确认恢复。

流式中断和验收

已经向前端发送部分文字后断流，要标记“未完成”，保留请求状态。重新生成时使用新的消息或明确替换旧内容，不能把新回复直接接到旧片段后面，伪装成同一份完整答案。工具调用流更要等参数完整并验证后执行。

用模拟响应测试超时、429、支出上限、非法参数、用户取消和半途断流，再做获准联调。监控每次尝试与最终状态，日志不含密钥和原始敏感输入。本文没有真实故障注入或服务 SLA 数据，不规定所有 529 都必须等待固定秒数。