api-rate-limiting-helper

API Rate Limiting Skill

Design complete rate limiting, quota, and retry systems for any API.

---

Rate Limiting Algorithms

Algorithm	Best For	Trade-offs
Token bucket	Bursty traffic with sustained avg	Allows bursts; slightly complex
Leaky bucket	Strict rate enforcement	Smooths bursts; can feel slow
Fixed window	Simple counting	Boundary spike problem
Sliding window log	Precise limiting	Memory-intensive
Sliding window counter	Balance of precision/memory	Best for most APIs

Recommendation: Use sliding window counter for API endpoints, token bucket for streaming/upload endpoints.

---

Response Headers (RFC standard)

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1700000060
X-RateLimit-Policy: 100;w=60;comment="per minute"
Retry-After: 18

429 Response Body

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. You have exceeded 100 requests per minute.",
  "retry_after_seconds": 18,
  "limit": 100,
  "window": "60s",
  "reset_at": "2024-01-01T00:01:00Z"
}

---

Tiered Quota Design

Tier	Requests/min	Requests/day	Burst	Concurrent
Free	10	1,000	20	2
Starter	100	50,000	200	10
Pro	1,000	500,000	2,000	50
Enterprise	Custom	Unlimited	Custom	Custom

Quota Endpoints

GET  /api/v1/account/quota         — current usage vs limits
GET  /api/v1/account/quota/history — usage over time

Response:

{
  "plan": "pro",
  "period": "2024-01",
  "limits": { "requests_per_minute": 1000, "requests_per_day": 500000 },
  "usage": { "requests_today": 12345, "requests_this_minute": 234 },
  "resets_at": "2024-02-01T00:00:00Z"
}

---

Retry Logic (client-side)

Exponential backoff with jitter

import random, time

def retry_with_backoff(fn, max_retries=5, base_delay=1.0, max_delay=60.0):
    for attempt in range(max_retries):
        try:
            return fn()
        except RateLimitError as e:
            if attempt == max_retries - 1:
                raise
            # Use Retry-After header if present, else exponential backoff
            delay = min(
                e.retry_after or (base_delay * (2 ** attempt)),
                max_delay
            )
            # Add jitter to prevent thundering herd
            delay += random.uniform(0, delay * 0.1)
            time.sleep(delay)