Retries

Retry dataclass

Retry(
    max_retries: int = 2,
    statuses: Collection[int] = frozenset(
        {408, 429, 502, 503, 504}
    ),
    methods: Collection[str] = frozenset(
        {"GET", "HEAD", "OPTIONS", "PUT", "DELETE"}
    ),
    connection_errors: bool = True,
    backoff: float = 0.5,
    max_delay: float = 30.0,
    jitter: float = 0.25,
    respect_retry_after: bool = True,
)

When to re-send a request, and how long to wait first.

Pass one as retry= to a client (or with_options). Each attempt goes through the client's prepare_request hook again, so signatures and timestamps are fresh. Only idempotent methods are retried by default: add "POST" if your API deduplicates with idempotency keys.

Delays grow exponentially (backoff * 2**attempt, capped at max_delay) with random jitter, unless the response carries a Retry-After header.

Example

api = Api(url, retry=nanosdk.Retry(max_retries=5, statuses={429, 503}))

Subclass it and override should_retry or delay for custom rules; the client's _retry_policy hook picks a policy per route.

Parameters:

Name	Type	Description	Default
max_retries	int	Retries after the first attempt (so up to max_retries + 1 tries).	2
statuses	Collection[int]	Response status codes that are retried.	frozenset({408, 429, 502, 503, 504})
methods	Collection[str]	HTTP methods that are retried.	frozenset({'GET', 'HEAD', 'OPTIONS', 'PUT', 'DELETE'})
connection_errors	bool	Whether to retry when no response arrived at all.	True
backoff	float	Delay before the first retry, in seconds; doubles each attempt.	0.5
max_delay	float	Upper bound for any single delay, in seconds (Retry-After included).	30.0
jitter	float	Randomise each delay by up to plus or minus this fraction.	0.25
respect_retry_after	bool	Use the response's Retry-After header (seconds or HTTP date) as the delay when present.	True

Methods:

Name	Description
should_retry	Decide whether to send the request again.
delay	Seconds to wait before the next attempt.

should_retry

should_retry(
    attempt: int,
    request: Request,
    response: Response | None,
) -> bool

Decide whether to send the request again.

Parameters:

Name	Type	Description	Default
attempt	int	Retries made so far (0 after the first attempt).	required
request	Request	The request that was sent.	required
response	Response | None	The response, or None if the attempt failed with a transport error (connection refused, timeout, ...).	required

Returns:

Type	Description
bool	True to retry after delay seconds.

delay

delay(attempt: int, response: Response | None) -> float

Seconds to wait before the next attempt.

Parameters:

Name	Type	Description	Default
attempt	int	Retries made so far (0 after the first attempt).	required
response	Response | None	The response that triggered the retry, or None after a transport error.	required

Returns:

Type	Description
float	The Retry-After delay if present and respected, otherwise exponential
float	backoff with jitter; never more than max_delay.