Retry-After — Complete Client Backoff Strategy Guide

In this tutorial, you will learn about Retry. We cover key concepts, practical examples, and best practices to help you master this topic.

The Retry-After header is included in 429 rate limit responses to indicate how long the client should wait before retrying. Proper client behavior includes exponential backoff and jitter.

What You'll Learn

You'll learn how to implement Retry-After, client exponential backoff, and retry strategies.

Why It Matters

Without Retry-After, clients retry immediately, creating a retry storm that overwhelms the API. Proper backoff reduces retry pressure and increases success rates.

Real-World Use

Stripe recommends exponential backoff with jitter. After a 429, wait 1 second, then 2, 4, 8 seconds. Add random jitter to prevent all clients retrying simultaneously.

Implementation

import time
import random
import requests

def exponential_backoff(api_call, max_retries=5):
    for attempt in range(max_retries):
        response = api_call()
        if response.status_code != 429:
            return response
        retry_after = response.headers.get("Retry-After")
        if retry_after:
            wait = int(retry_after)
        else:
            wait = min(2 ** attempt + random.random(), 60)
        print(f"429, waiting {wait:.1f}s (attempt {attempt + 1})")
        time.sleep(wait)
    raise Exception("Max retries exceeded")

def call_api():
    return requests.get("https://api.example.com/data", headers={"Authorization": "Bearer token"})

response = exponential_backoff(call_api)
print(f"Status: {response.status_code}")

# Server-side retry-after calculation
def rate_limit_response(retry_seconds=60):
    response = jsonify({"error": "Rate limit exceeded"})
    response.status_code = 429
    response.headers["Retry-After"] = str(retry_seconds)
    return response

Common Mistakes

| Mistake | Fix | |---------|-----| | Immediate retry without waiting | Retry storm overwhelms API | Always wait before retry | | No jitter | All clients retry simultaneously | Add random jitter to backoff | | Infinite retries | Never gives up | Set max retry limit | | Ignoring Retry-After header | Overrides server suggestion | Always honor Retry-After | | Fixed delay instead of backoff | Wastes time on short limits | Start with 1s, double each retry |

Practice Questions

1. What is exponential backoff?
2. Why is jitter important?
3. How should clients use the Retry-After header?
4. What is a retry storm?
5. What is the maximum recommended retry delay?

Challenge

Implement a client with exponential backoff and jitter. Test against a rate-limited API. Verify that retries happen at increasing intervals.

What's Next

Complete the Rate Limiting project.