Claude Agent SDK 错误处理与重试机制

简介

调用 Anthropic API 网络波动、服务限流、参数错误、token 超限都会抛出异常。生产环境必须完善错误捕获、重试、熔断，避免程序直接崩溃，提升服务稳定性。

重点区分

客户端错误（4xx）：参数错误、鉴权失败、提示词违规，不建议重试

服务端/网络错误（5xx、429、网络超时）：临时故障，可按策略重试

前置准备

Python3.10+ / Node.js 18+
SDK 安装

# Python
pip install anthropic tenacity
# TS
npm install @anthropic-ai/sdk p-retry

tenacity：Python 重试库
p-retry：Node.js 重试工具库

错误类型总览

错误类型	状态码	原因	是否重试
AuthenticationError	401	API Key 错误、密钥过期	❌ 不重试
PermissionDeniedError	403	账号无权限、地区限制	❌ 不重试
NotFoundError	404	模型不存在	❌ 不重试
RateLimitError	429	请求速率超限（限流）	✅ 指数退避重试
BadRequestError	400	参数错误、提示词超长、格式错误	❌ 不重试
TooManyTokensError	400	上下文 token 超出模型上限	❌ 不重试
InternalServerError	5xx	Anthropic 服务内部异常	✅ 有限次数重试
APIConnectionError	–	网络超时、DNS、连接失败	✅ 重试

核心重试策略：指数退避（Exponential Backoff）

指数退避：每次重试等待时间成倍增加，配合随机抖动（jitter），防止大量客户端同时发起请求造成流量风暴。
公式示例：
等待时间 = base * (2^重试次数) ± random抖动
推荐配置：

最大重试次数：3次
初始等待：1秒
最大等待上限：10秒

429 限流响应头 Retry-After：优先读取这个头部的等待时间，覆盖默认退避时间。

实战1：Python SDK 完整错误捕获 + 重试

import os
from anthropic import Anthropic, APIConnectionError, RateLimitError, InternalServerError, BadRequestError, AuthenticationError
from tenacity import retry, stop_after_attempt, wait_exponential_jitter, retry_if_exception_typeclient = Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))
@retry(
    stop=stop_after_attempt(3),  # 最多重试3次
    wait=wait_exponential_jitter(initial=1, max=10), # 指数退避+随机抖动
    retry=retry_if_exception_type((APIConnectionError, RateLimitError, InternalServerError)),
    reraise=True
)
def call_claude(prompt: str):
    try:
        resp = client.messages.create(
            model="claude-3-5-sonnet-latest",
            max_tokens=1024,
            messages=[{"role": "user", "content": prompt}]
        )
        return resp.content[0].text
    except AuthenticationError:
        print("API Key 认证失败，请检查密钥")
        raise
    except BadRequestError as e:
        print(f"请求参数错误：{e}")
        raise
    except RateLimitError as e:
        # 读取 Retry-After 头部
        retry_after = e.response.headers.get("retry-after") if e.response else None
        if retry_after:
            print(f"触发限流，服务建议等待 {retry_after}s")
        raise
if name == "main":
    try:
        result = call_claude("解释什么是MCP协议")
        print(result)
    except Exception as err:
        print(f"最终调用失败: {err}")

实战2：TypeScript / Node.js 错误处理 + p-retry

import Anthropic, {
  APIConnectionError,
  RateLimitError,
  InternalServerError,
  BadRequestError,
  AuthenticationError
} from "@anthropic-ai/sdk";
import pRetry from "p-retry";const anthropic = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});
async function callClaude(prompt: string): Promise<string> {
  return pRetry(async () => {
    try {
      const res = await anthropic.messages.create({
        model: "claude-3-5-sonnet-latest",
        max_tokens: 1024,
        messages: [{ role: "user", content: prompt }],
      });
      return res.content[0].text;
    } catch (err: any) {
      // 区分异常类型，不可重试错误直接抛出终止
      if (err instanceof AuthenticationError) {
        throw new pRetry.AbortError("API Key认证失败");
      }
      if (err instanceof BadRequestError) {
        throw new pRetry.AbortError(请求参数错误: ${err.message});
      }
      // 429 读取 Retry-After
      if (err instanceof RateLimitError && err.response?.headers["retry-after"]) {
        const waitSec = err.response.headers["retry-after"];
        console.log(限流，建议等待${waitSec}秒);
      }
      throw err;
    }
  }, {
    retries: 3,
    minTimeout: 1000,
    maxTimeout: 10000,
    randomize: true
  });
}
(async () => {
  try {
    const text = await callClaude("解释什么是MCP协议");
    console.log(text);
  } catch (e) {
    console.error("最终调用失败", e);
  }
})();

超时设置

必须给 API 请求增加超时时间，防止请求无限阻塞。
Python：

client = Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY"), timeout=20.0)

TS：

const anthropic = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
  timeout: 20 * 1000
});

熔断机制（生产环境进阶）

重试只解决瞬时抖动；短时间大量失败时，需要熔断，停止调用API，保护服务。
简单逻辑：

统计最近N次请求失败率
失败率超过阈值（例如50%），打开熔断
熔断窗口期内，直接跳过API调用，返回降级结果
窗口期结束，放少量请求做探测，探测成功则关闭熔断

Python 推荐 pybreaker；Node.js 推荐 opossum

工具调用场景下的错误处理要点

工具函数自身异常：工具执行报错，需要包装错误信息放入 tool_result 返回给Agent，不能直接中断整个会话。
工具参数校验失败：返回结构化错误，让Agent可以选择重试调用工具或者放弃。
工具调用循环：增加最大工具调用轮次限制，防止无限来回调用工具，耗尽token。

示例：工具异常返回

tool_result = {"status": "error", "msg": "读取文件失败：权限不足"}

日志与监控（生产必备）

每次请求记录：请求ID、耗时、模型名称、token消耗、错误类型
告警：429激增、5xx错误率升高、认证错误持续出现
区分业务报错和平台API报错，方便定位问题

最佳实践

区分可重试/不可重试异常，4xx参数/鉴权类错误禁止重试，避免浪费额度。
重试次数不要过大，3次是大多数业务的最优值。
限流优先使用 Retry-After 响应头，比固定退避更友好。
所有请求设置超时，防止长连接卡死。
子代理并行场景：单独给每个子代理设置重试，单个子任务失败不影响整体任务。
做好降级方案：API不可用时返回预设提示，不要直接抛出堆栈给前端用户。

常见问题

Q：重试会不会重复生成内容？

A：Anthropic API 幂等性：推荐带上 idempotency-key 请求头，防止重试造成重复计费。

Q：429 限流，是全局限制还是单key限制？

A：按API Key 维度限制RPM，并发越高越容易触发，需要搭配并发池控制。

Q：流式请求如何处理断连重试？

A：保存完整 messages 上下文记录，连接断开后，使用完整消息历史重新发起流式请求。

小结

错误处理核心：分类捕获异常、仅对临时故障执行指数退避重试，设置超时，生产环境叠加熔断。
并行子代理、工具调用场景，需要单独处理工具内部异常，做好日志和降级策略。

简介