重试

重试

用 RetryPolicy 配置重试 —— 尝试次数、可重试的状态码、退避，以及重试响应头的处理。

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；为 0 则禁用退避。

backoff_max

class-attribute instance-attribute

backoff_max: float = 5.0

最大退避延迟，单位为秒；为 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 表示不设上限。

当某次重试的延迟会达到或超过预算时，就在重试之前停止，并重新抛出最后一个错误。