重试

typesafe_sdk.RetryPolicy

dataclass

RetryPolicy(
    max_retries: int = 2,
    backoff_initial: float = 0.5,
    backoff_max: float = 5.0,
    backoff_jitter: float = 0.25,
    http_statuses: set[int] = (
        lambda: {408, 429, *range(500, 600)}
    )(),
    respect_retry_after: bool = True,
    api_connection_error: bool = True,
    api_timeout_error: bool = True,
    exceptions: set[
        type[BaseException]
    ] = set(),
    predicate: Callable[[BaseException], bool]
    | None = None,
    timeout: float | None = 30.0,
)

SDK 重试行为的配置。

示例：

from typesafe_sdk import RetryPolicy, TypeSafeClient

client = TypeSafeClient(
    retry=RetryPolicy(
        max_retries=3, timeout=10.0, http_statuses={429, 500, 502, 503, 504}
    )
)

max_retries

class-attribute instance-attribute

max_retries: int = 2

初次尝试之后的最大重试次数；0 表示禁用重试。

backoff_initial

class-attribute instance-attribute

backoff_initial: float = 0.5

首次退避延迟（秒），此后每次尝试翻倍，直至 backoff_max；零表示禁用退避。

backoff_max

class-attribute instance-attribute

backoff_max: float = 5.0

最大退避延迟（秒）；零表示禁用退避。

backoff_jitter

class-attribute instance-attribute

backoff_jitter: float = 0.25

从每次退避延迟中随机扣减的比例，介于 0 和 1 之间。

http_statuses

class-attribute instance-attribute

http_statuses: set[int] = field(
    default_factory=lambda: {
        408,
        429,
        *range(500, 600),
    }
)

会触发重试的 HTTP 状态码。

respect_retry_after

class-attribute instance-attribute

respect_retry_after: bool = True

是否遵循 Retry-After 和 retry-after-ms 响应头。

api_connection_error

class-attribute instance-attribute

api_connection_error: bool = True

是否重试 TypeSafeAPIConnectionError，该异常在请求无法连接服务器或无法从服务器读取数据时抛出。

api_timeout_error

class-attribute instance-attribute

api_timeout_error: bool = True

是否重试 TypeSafeAPITimeoutError，该异常在请求超出其超时时间时抛出。

exceptions

class-attribute instance-attribute

exceptions: set[type[BaseException]] = field(
    default_factory=set
)

在内置规则之外，额外触发重试的异常类型。

predicate

class-attribute instance-attribute

predicate: (
    Callable[[BaseException], bool] | None
) = None

可选的谓词函数，以抛出的异常为参数被调用；除其他规则外，返回 True 还会额外触发一次重试。

timeout

class-attribute instance-attribute

timeout: float | None = 30.0

每次 SDK 调用的总重试预算（秒），包括初次尝试和各次延迟；None 表示禁用该限制。

若某次重试的延迟会达到或超过该预算，则在其开始之前停止，并重新抛出最后一个错误。