Retry Handler

Implement a configurable retry handler with exponential backoff and jitter. Fixed delays hammer a struggling server; exponential backoff gives it progressively more breathing room. Jitter randomizes the delay so all retrying clients do not wake up simultaneously (thundering herd). max_delay caps the wait to prevent unbounded blocking.

“Exponential backoff without jitter creates synchronized thundering herds. Jitter is not optional - it is the point of not making a struggling server worse. Never retry non-retryable errors. GET is always safe to retry; POST requires an idempotency key.”

import time
import random
from typing import Callable, Any

class RetryHandler:
    def __init__(self, max_retries: int = 5, base_delay: float = 1.0, max_delay: float = 30.0):
        self.max_retries = max_retries
        self.base_delay = base_delay
        self.max_delay = max_delay

    def execute(self, func: Callable, *args, **kwargs) -> Any:
        last_exception = None
        for attempt in range(self.max_retries):
            try:
                return func(*args, **kwargs)
            except Exception as e:
                last_exception = e
                if attempt == self.max_retries - 1:
                    break
                delay = min(self.base_delay * (2 ** attempt), self.max_delay)
                jitter = random.uniform(0, delay * 0.1)
                time.sleep(delay + jitter)
        raise RuntimeError(f"Failed after {self.max_retries} attempts") from last_exception


# Usage
call_count = {"n": 0}

def flaky_function():
    call_count["n"] += 1
    print(f"  Attempt #{call_count['n']}")
    if call_count["n"] < 3:
        raise Exception("Simulated failure")
    return "Success!"

handler = RetryHandler(max_retries=3, base_delay=0.5, max_delay=5.0)
result = handler.execute(flaky_function)
print(f"Result: {result}")

• 1Exponential Backoff - Progressive Breathing Room - delay = min(base_delay * 2^attempt, max_delay). Attempt 0: 0.5s. Attempt 1: 1s. Attempt 2: 2s. Attempt 3: 4s. Fixed delay keeps hammering a struggling server at full rate. Exponential gives it progressively more time to recover.
• 2Jitter - Preventing Thundering Herd - jitter = random.uniform(0, delay * 0.1). Without jitter, 1000 clients that all started retrying at the same moment sleep for exactly the same duration and wake up simultaneously - making the overloaded server 1000x worse at that instant. Jitter spreads the wake-ups.
• 3max_delay Cap - Bounding the Wait - min(..., max_delay) prevents 2^attempt from growing unboundedly. Without it, attempt 30 would sleep for 2^30 * base_delay - over a billion seconds. In languages without Python's arbitrary-precision integers this is also an integer overflow bug. max_delay sets a practical ceiling.
• 4Exception Chain - Preserving Root Cause - raise RuntimeError(...) from last_exception preserves the original exception as __cause__. Without the from clause, the original error is lost and debugging becomes much harder. Always chain exceptions in retry wrappers.