Python中转服务使用tenacity库对claude接口重试时的异常捕获边界

文章导读
处理Claude接口的中转服务,重试逻辑写不好,线上问题往往先从超时和报错堆栈里暴露出来。我自己的排查习惯是先看异常类型,再看重试配置,最后看调用方拿到的错误信息。很多重试失效或误重试,根源都是异常捕获边界没有划清楚。
📋 目录
  1. 壹 包装一层自定义异常,让重试逻辑只依赖自己的类型
  2. 贰 等待时间和异步环境同样决定边界是否有效
  3. 叁 重试结束后的异常传播,不能在外层吞掉
  4. 肆 用mock客户端验证异常捕获边界
A A

处理Claude接口的中转服务,重试逻辑写不好,线上问题往往先从超时和报错堆栈里暴露出来。我自己的排查习惯是先看异常类型,再看重试配置,最后看调用方拿到的错误信息。很多重试失效或误重试,根源都是异常捕获边界没有划清楚。

在决定对Claude接口调用是否重试之前,先要明确哪些异常属于可重试的临时故障。通常连接断开、超时、429限流以及5xx服务端错误都可以安全重试;而400参数错误、401鉴权失败、403权限不足或404不存在属于业务或配置问题,重试不会改变结果,反而延长用户等待。你可以利用tenacity的retry_if_exception_type,配合anthropic库自身抛出的异常类型做判断:先捕获APIConnectionError和APIStatusError,再检查其中status_code是否落在可重试范围。这样既能覆盖常见网络抖动,又避免对永久性错误做无谓的尝试。

这里有一个容易忽略的点:APIConnectionError没有status_code属性,而APIStatusError带有status_code。所以如果直接用retry_if_exception_type(APIConnectionError)当然可以,但要把429和5xx单独拿出来判断。我通常写一个判断函数:

from anthropic import APIConnectionError, APIStatusError

class ClaudeRetryableError(Exception):
    pass

def is_retryable(exc: Exception) -> bool:
    if isinstance(exc, APIConnectionError):
        return True
    if isinstance(exc, APIStatusError):
        return exc.status_code in (429, 500, 502, 503, 504)
    return False

这个函数可以直接传给tenacity的retry_if_exception,让重试逻辑只响应可重试的异常。注意不要在这里返回True给所有APIStatusError,否则401和400也会被重试。

包装一层自定义异常,让重试逻辑只依赖自己的类型

实际编码时,建议定义两个自定义异常基类,比如RetryableError和NonRetryableError。在转发服务内部,把anthropic抛出的异常通过一个包装函数转换成这两种之一:网络类错误、限流、5xx归为RetryableError;4xx非限流归为NonRetryableError。然后用tenacity的@retry装饰器,设置retry_if_exception_type为RetryableError,并搭配wait_exponential。这样重试逻辑只关注自定义异常,不会因为底层库升级而失效。注意在包装时,务必把原始异常作为context保留,便于后续日志排查。

Python中转服务使用tenacity库对claude接口重试时的异常捕获边界

具体实现时,包装函数要放在实际调用Claude API的方法内部,在捕获到异常后抛出包装后的类型,tenacity才会根据retry_if_exception_type触发重试。例如:

import tenacity
from anthropic import APIConnectionError, APIStatusError

class RetryableError(Exception):
    def __init__(self, message, original_exc):
        super().__init__(message)
        self.original_exc = original_exc

class NonRetryableError(Exception):
    def __init__(self, message, original_exc):
        super().__init__(message)
        self.original_exc = original_exc

def wrap_claude_error(exc: Exception) -> Exception:
    if isinstance(exc, APIConnectionError):
        return RetryableError(f"claude connection error: {exc}", exc)
    if isinstance(exc, APIStatusError):
        if exc.status_code in (429, 500, 502, 503, 504):
            return RetryableError(f"claude status {exc.status_code}", exc)
        return NonRetryableError(f"claude status {exc.status_code}", exc)
    return NonRetryableError(f"unexpected: {exc}", exc)

@tenacity.retry(
    retry=tenacity.retry_if_exception_type(RetryableError),
    wait=tenacity.wait_exponential(multiplier=1, min=1, max=30),
    stop=tenacity.stop_after_attempt(4),
    reraise=True
)
def call_claude_with_retry(prompt):
    try:
        # 假设这里调用Claude SDK,例如 client.messages.create(...)
        return your_claude_call(prompt)
    except Exception as e:
        raise wrap_claude_error(e)

这里的关键是@retry放在最内层,且函数内只抛出包装后的异常。如果还有别的HTTP调用也抛异常,要小心不要误包装。

等待时间和异步环境同样决定边界是否有效

等待策略是另一个边界。wait_exponential如果设置得过宽,比如max=300,一次重试可能要等5分钟,在线转发服务根本扛不住。更常见的是漏了stop_after_attempt或stop_after_delay,重试永远不结束,worker资源被占满。我建议把最大等待时间控制在30秒内,并明确设置最大尝试次数。另外,如果你在异步环境(如FastAPI、aiohttp)中使用tenacity,必须使用AsyncRetrying类,而不是普通的@retry装饰器,否则会阻塞事件循环。

Python中转服务使用tenacity库对claude接口重试时的异常捕获边界
from tenacity import AsyncRetrying, retry_if_exception_type, stop_after_attempt, wait_exponential

async def call_claude_async(prompt):
    async for attempt in AsyncRetrying(
        retry=retry_if_exception_type(RetryableError),
        wait=wait_exponential(multiplier=1, min=1, max=30),
        stop=stop_after_attempt(3),
        reraise=True
    ):
        with attempt:
            return await do_claude_request(prompt)

注意,Claude API的429响应中可能带有Retry-After头,tenacity的wait_exponential不会自动读取这个头。如果需要尊重服务端的限流时间,需要手动从异常中提取Retry-After,并作为本次等待时间。我的做法是在包装异常时把Retry-After放到RetryableError的一个字段里,然后在自定义等待策略中读取。

重试结束后的异常传播,不能在外层吞掉

最关键的边界是重试结束后的异常传播。tenacity默认在尝试次数耗尽后会把最后一次抛出的异常继续向外抛,这在转发服务里是正确行为,因为客户端需要拿到最终失败原因。但如果你在外层再加了一层try/except,并且把所有异常都吞掉,就可能返回一个空壳响应,或者在重试过程中出现一个中间成功却又再次失败的情况。所以应当把retry装饰器放在最内层的方法上,外层只做日志记录,不再二次捕获。如果使用了reraise参数,要确保它保持原异常类型和堆栈,避免客户端收到被改写过的错误信息。

具体到中转服务,外层可以做错误映射,但不能吞掉异常。比如用Flask写一个转发接口,重试结束后应该根据异常类型返回对应的http状态码和错误信息,而不是捕获后返回200:

from flask import jsonify

@app.route('/v1/messages', methods=['POST'])
def proxy():
    try:
        result = call_claude_with_retry(request.json.get('prompt'))
        return jsonify(result)
    except RetryableError as e:
        logger.error("claude retry exhausted", exc_info=e.original_exc)
        return jsonify({"error": "upstream temporarily unavailable"}), 502
    except NonRetryableError as e:
        logger.warning("claude rejected request", exc_info=e.original_exc)
        return jsonify({"error": "invalid request"}), 400

注意,这里外层只负责把自定义异常转换成HTTP响应,没有再次重试。如果你直接用anthropic库的原始异常,也可以用相同的思路,但建议在包装层转为自定义异常,这样外层逻辑更稳定。

Python中转服务使用tenacity库对claude接口重试时的异常捕获边界

用mock客户端验证异常捕获边界

要验证异常捕获边界是否设对,可以写一个mock客户端,让它依次抛出不同类型的异常。比如第一次抛APIConnectionError,第二次抛429限流,第三次成功,观察重试是否按预期进行。同时还要模拟非重试异常,比如401,确认它不会被重试而是立即抛出。用unittest.mock的side_effect可以轻松实现。

from unittest.mock import Mock, patch
import anthropic

def test_retry_logic():
    calls = []
    def fake_request(prompt):
        calls.append(len(calls))
        if len(calls) == 1:
            raise anthropic.APIConnectionError("conn lost")
        if len(calls) == 2:
            raise anthropic.APIStatusError("rate limited", response=Mock(status_code=429))
        return {"ok": True}

    # 假设 your_claude_call 是你在包装函数里调用的方法
    with patch("__main__.your_claude_call", side_effect=fake_request):
        result = call_claude_with_retry("hello")
        assert result == {"ok": True}
    assert len(calls) == 3

这个测试里,第一次和第二次抛出可重试异常,第三次成功,所以total调用次数是3。如果你的重试配置是stop_after_attempt(4),这里也能验证是否在第三次就退出循环。如果日志里看到重试次数和等待间隔都符合配置,并且最终抛出的异常类型与原始一致,就说明边界正确。另一个检查点是调用方能否收到最终异常信息,而不是被转发服务静默吞掉。

除了正向测试,还要覆盖NonRetryableError的场景。比如让fake_request第一次就抛APIStatusError(status_code=401),然后断言调用次数只有1,且调用方收到NonRetryableError。这样才算把边界锁住。