tenacity

tenacity adds configurable retry logic to any callable - exponential backoff, jitter, stop conditions, and hooks - without hand-rolling while loops around flaky network or database calls.

Recipe

from tenacity import retry, stop_after_attempt, wait_exponential_jitter
 
 
@retry(stop=stop_after_attempt(3), wait=wait_exponential_jitter(initial=1, max=10))
def fetch_status() -> dict:
    response = httpx.get("https://api.example.com/health", timeout=5.0)
    response.raise_for_status()
    return response.json()

When to reach for this:

• Transient HTTP 502/503/timeout errors from upstream APIs
• Database deadlocks or connection blips
• Cloud API throttling (combined with rate-limit awareness)
• Worker tasks that should survive brief infrastructure hiccups

Working Example

from __future__ import annotations
 
import logging
 
import httpx
from tenacity import (
    before_sleep_log,
    retry,
    retry_if_exception_type,
    stop_after_attempt,
    wait_exponential_jitter,
)
 
logger = logging.getLogger(__name__)
 
 
class TransientError(Exception):
    pass
 
 
def _raise_for_transient(response: httpx.Response) -> None:
    if response.status_code >= 500:
        raise TransientError(f"server error {response.status_code}")
    response.raise_for_status()
 
 
@retry(
    retry=retry_if_exception_type((TransientError, httpx.TimeoutException)),
    stop=stop_after_attempt(5),
    wait=wait_exponential_jitter(initial=0.5, max=8),
    before_sleep=before_sleep_log(logger, logging.WARNING),
    reraise=True,
)
def charge_customer(customer_id: str, amount_cents: int) -> str:
    with httpx.Client(timeout=10.0) as client:
        response = client.post(
            "/charges",
            json={"customer_id": customer_id, "amount_cents": amount_cents},
            headers={"Idempotency-Key": f"{customer_id}:{amount_cents}"},
        )
        _raise_for_transient(response)
        return response.json()["id"]
 
 
if __name__ == "__main__":
    logging.basicConfig(level=logging.INFO)
    print(charge_customer("cus_1", 1999))

What this demonstrates:

• Retries only TransientError and timeouts - not 4xx client mistakes
• Exponential backoff with jitter reduces thundering herds
• before_sleep_log surfaces retry attempts in logs
• Idempotency header paired with retries for payment safety
• reraise=True preserves the final exception after exhaustion

Deep Dive

How It Works

• Decorators - @retry wraps sync functions; use @retry on async functions with async-compatible wait/stop (or AsyncRetrying context).
• Stop policies - Combine stop_after_attempt, stop_after_delay, stop_any.
• Wait policies - Fixed, exponential, random, or custom callable.
• Retry predicates - retry_if_exception, retry_if_result, retry_unless_exception_type.

Retry Decision Matrix

Python Notes

from tenacity import Retrying
 
# Imperative style inside a loop body
for attempt in Retrying(stop=stop_after_attempt(3)):
    with attempt:
        do_work()

Gotchas

• Retrying non-idempotent POST - Double charges or duplicate records. Fix: idempotency keys or dedupe table.
• Infinite retry on bad config - Wrong URL retries forever with cron. Fix: stop_after_attempt plus alert on final failure.
• Catching bare Exception - Masks programming bugs. Fix: narrow retry_if_exception_type.
• No jitter - Synchronized clients retry together and DDoS the recovering service. Fix: wait_exponential_jitter.
• Retry inside retry - Nested decorators multiply attempts. Fix: one retry boundary per outbound call.
• Silent failures - Swallowing the last exception hides outages. Fix: reraise=True and metrics on retry count.

Alternatives

FAQs

Related

• httpx & requests - HTTP clients to wrap
• Retries and Backoff - application-level patterns
• celery - distributed task retries
• Rate Limiting - when not to retry

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+.