重試

用 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 表示不設上限。

當某次重試的延遲會達到或超過預算時，就在重試之前停止，並重新丟擲最後一個錯誤。