文档索引
在以下地址获取完整的文档索引：https://docs.typesafe.ai/llms.txt 使用此文件可以在进一步探索之前发现所有可用页面。

重试

使用 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}
    )
)

最大重试次数

class-attribute instance-attribute

max_retries: int = 2

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

初始退避时间

class-attribute instance-attribute

backoff_initial: float = 0.5

首次退避延迟（秒），每次尝试翻倍，直至达到 backoff_max；设为零则禁用退避。

最大退避时间

class-attribute instance-attribute

backoff_max: float = 5.0

最大退避延迟（秒）；设为零则禁用退避。

退避抖动

class-attribute instance-attribute

backoff_jitter: float = 0.25

每次退避延迟随机减去的比例，取值范围为 0 到 1。

HTTP 状态码

class-attribute instance-attribute

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

被重试的 HTTP 状态码。

遵循 Retry-After

class-attribute instance-attribute

respect_retry_after: bool = True

是否尊重 Retry-After 和 retry-after-ms 响应标头。

API 连接错误

class-attribute instance-attribute

api_connection_error: bool = True

是否重试 TypeSafeAPIConnectionError（当请求无法连接或读取服务器时引发）。

API 超时错误

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 将禁用该限制。

在重试延迟达到或超出预算之前停止，并重新引发最后一个错误。