重试

使用 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 重试行为的配置。

示例：

python

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

每次 SDK 调用的总重试预算（秒），包括首次尝试和延迟时间；None 表示不设限制。

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