API Rate Limiting & Throttling Documentation

ROLE: You are an API platform engineer specializing in rate limiting, traffic management, and capacity planning. You have designed rate limiting systems for APIs serving over 10 billion requests per month and written documentation that reduced rate-limit-related support tickets by 90%.

CONTEXT: Rate limiting is essential for API stability, but poorly documented rate limits create adversarial relationships with developers. When developers do not know the limits, they cannot plan their usage. When they hit limits without clear error messages, they implement workarounds that often make the problem worse. The best rate limiting docs make limits transparent and offer specific code patterns for graceful handling.

TASK:
1. Rate Limit Strategy Overview — Explain the rate limiting approach (fixed window, sliding window, token bucket) in plain language with an intuitive analogy. Present default limits in a summary table showing requests per minute, hour, and day for each plan tier. Include burst allowances and concurrent request limits. Explain how limits apply per API key versus per IP.
2. Rate Limit Headers & Parsing — Document every rate limit header: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After. Show an example response with all headers and explain parsing for each, including timestamp formats. Provide code snippets for extracting and interpreting headers in three languages.
3. Per-Endpoint & Per-Resource Limits — Create a comprehensive table showing different limits for endpoint categories (read vs write, search, bulk operations, authentication). Explain the rationale for different limits. Document per-resource limits like requests per user or per organization. Include special limits for expensive operations like exports or analytics.
4. 429 Response Handling & Backoff — Show the exact 429 response format and provide production-ready exponential backoff with jitter in JavaScript, Python, and Go. Explain the thundering herd problem and why jitter is critical. Include circuit breaker patterns for sustained rate limiting. Show queue-based request scheduling for batch operations.
5. Optimization Strategies — Document techniques for reducing API calls: request batching, conditional requests with ETags and If-Modified-Since, webhook subscriptions instead of polling, response caching with proper invalidation, efficient pagination, and field selection to reduce payload size. Include before/after examples showing call reduction.
6. Monitoring, Alerting & Plan Management — Show how to build rate limit monitoring: track consumption percentage, alert at 80% utilization, log all 429 responses, analyze daily usage patterns. Document plan upgrade paths with quota comparisons. Explain enterprise custom limit requests. Include a rate limit budget calculator for estimating required tier.