Retries & Backoff

Transient network and infrastructure failures often succeed on retry. Use bounded attempts, exponential backoff with jitter, and retry only idempotent operations - libraries like tenacity encode the pattern cleanly.

Recipe

import random
import time
 
def retry(callable_fn, attempts=3, base=0.5):
    for attempt in range(1, attempts + 1):
        try:
            return callable_fn()
        except TransientError:
            if attempt == attempts:
                raise
            delay = base * (2 ** (attempt - 1)) + random.uniform(0, 0.1)
            time.sleep(delay)

When to reach for this:

• HTTP 429/503, connection resets, DNS blips
• Database deadlock or serialization failures (with care)
• Message queue publish timeouts
• Cloud API rate limits with Retry-After semantics
• NOT for validation errors or 4xx client mistakes

Working Example

Manual retry with jitter, then equivalent tenacity-style structure (stdlib-only demo).

import random
import time
from dataclasses import dataclass
 
class TransientError(Exception):
    pass
 
@dataclass
class FakeClient:
    calls: int = 0
    fail_until: int = 2
 
    def get(self) -> str:
        self.calls += 1
        if self.calls <= self.fail_until:
            raise TransientError(f"attempt {self.calls}")
        return "ok"
 
def with_retry(client: FakeClient, attempts: int = 5) -> str:
    for attempt in range(1, attempts + 1):
        try:
            return client.get()
        except TransientError as exc:
            if attempt == attempts:
                raise RuntimeError("exhausted retries") from exc
            delay = min(2.0, 0.2 * (2 ** (attempt - 1))) + random.uniform(0, 0.05)
            time.sleep(delay)
    raise RuntimeError("unreachable")
 
client = FakeClient()
print(with_retry(client), "calls:", client.calls)

What this demonstrates:

• Cap attempts and raise chained error when exhausted
• Exponential backoff capped to avoid multi-minute waits in sync code
• Jitter reduces thundering herd on recovery
• Count calls in tests to verify retry behavior

Deep Dive

How It Works

• Classify exceptions into retriable vs permanent
• Backoff: delay = min(cap, base * 2**attempt) + jitter
• Idempotency: retries safe only if side effects are absent or deduplicated
• tenacity provides decorators: stop_after_attempt, wait_exponential, retry_if_exception_type
• Log each retry with attempt number and sleep duration

Retry Policy Table

Gotchas

• Retrying non-idempotent POST - duplicates charges/orders. Fix: idempotency keys or skip retry.
• Infinite retry loops - no stop condition burns CPU and masks outages. Fix: max attempts + circuit breaker.
• No jitter - synchronized clients retry together. Fix: random uniform or full jitter.
• Retrying too fast - worsens rate limits. Fix: honor Retry-After header when present.
• Swallowing final exception - return None after failures. Fix: raise with context on exhaustion.

Alternatives

FAQs

Related

• Raising & Chaining - final failure chain
• The logging Module - retry warnings
• Async HTTP with httpx/aiohttp - client timeouts
• Errors & Logging Best Practices - operational policy

Stack versions: This page was written for Python 3.14.0 (stable 3.14, maintenance 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.