Python API Rate Limit Handling — Core Concepts

Why this matters

Almost every public API enforces rate limits — Twitter allows 300 requests per 15 minutes, GitHub allows 5,000 per hour, OpenAI charges by token but also limits requests per minute. When your Python application integrates with external APIs, hitting rate limits is not a question of “if” but “when.” Programs that handle limits gracefully stay reliable; programs that ignore them crash, lose data, or get their API keys revoked.

How rate limits are communicated

HTTP 429 status code

The standard signal for “you are sending too many requests.” The response usually includes a Retry-After header telling you how many seconds to wait.

Rate limit headers

Most APIs send headers with every response, not just when you hit the limit:

Header	Meaning	Example
X-RateLimit-Limit	Maximum requests per window	100
X-RateLimit-Remaining	Requests left in current window	47
X-RateLimit-Reset	When the window resets (Unix timestamp)	1711584000
Retry-After	Seconds to wait before retrying	13

Not every API uses the same header names — GitHub uses x-ratelimit-*, Stripe uses ratelimit-*, and some APIs use completely custom formats. Always check the API documentation.

Three strategies for handling rate limits

1. Proactive pacing

Calculate the maximum request rate and add delays before each request:

If the limit is 100 requests per minute:
Minimum interval = 60 / 100 = 0.6 seconds between requests

This avoids hitting limits entirely. The downside is reduced throughput when the API could handle bursts.

2. Reactive backoff

Send requests normally and respond when rate limited:

• Receive a 429 response.
• Read the Retry-After header.
• Wait the indicated time, then retry.

This maximizes throughput but means some requests fail initially and need retries.

3. Adaptive approach (recommended)

Combine both: pace requests based on remaining quota, and fall back to retry-with-backoff if limits are hit despite pacing.

Monitor X-RateLimit-Remaining from each response. When remaining drops below a threshold (say 10%), slow down proactively. When a 429 arrives, back off and respect Retry-After.

Exponential backoff

When retrying after a rate limit, do not retry immediately at full speed. Use exponential backoff:

• First retry: wait 1 second
• Second retry: wait 2 seconds
• Third retry: wait 4 seconds
• Add random jitter (±0.5s) to avoid synchronized retries

This prevents a flood of retries from immediately triggering another rate limit. The tenacity library in Python provides this pattern out of the box.

Common misconception

“Rate limits only matter for high-traffic applications.” Even a simple script that fetches data in a loop can hit rate limits quickly. A loop calling an API endpoint 1,000 times with no delay will exhaust most rate limits in seconds. Rate limit handling is essential even for one-off scripts and batch jobs — not just production services.

Multiple API keys

Some developers try to circumvent rate limits by rotating multiple API keys. Most API providers detect this pattern (same IP, similar request patterns) and can suspend all associated keys. This is generally a Terms of Service violation. The ethical approach is to request higher limits from the provider or optimize your application to need fewer requests.

Key patterns summary

Pattern	When to use
Fixed delay	Simple scripts, known limit
Token bucket	Steady throughput with burst capacity
Header-based pacing	APIs with good rate limit headers
Exponential backoff	Retrying after 429 responses
Request batching	APIs that support bulk endpoints
Caching	Repeated requests for the same data

One thing to remember: Rate limit handling is a two-part discipline — pace your requests proactively by reading rate limit headers, and retry gracefully with exponential backoff when limits are hit. The combination keeps your application reliable without wasting API quota.