Your public API spikes after a viral integration. First calls come from a partner aggregator — 200 legit req/s. Your global 100 req/s per IP limit blocks them. Meanwhile a bot on 500 free-tier IPs nibbles /search untouched.
Bad rate limiting protects the server from bad clients and good ones at once.
Clear goals
Protect CPU/DB, ensure fairness across tenants, monetize premium tiers, absorb short bursts. Not security alone — determined attackers bypass basic limits.
Algorithms
| Algo | Behavior | Use case |
|---|---|---|
| Fixed window | Simple, edge spikes | Low internal |
| Sliding window | Fairer | Public API |
| Token bucket | Controlled burst | B2B partners |
| Leaky bucket | Steady outflow | Queues |
Redis + Lua or managed gateways.
Quota keys
Hierarchy: API key → plan → sensitive endpoint. IP last resort. Auth vs anon: separate pools.
Temporary whitelist for partner launch with contractual cap.
Client UX
Document limits in OpenAPI. Exponential backoff + jitter examples. Explicit 429 beats silent timeout.
Overage: 402/403 business vs 429 technical.
Load tests
Simulate 3× burst, verify recovery < 1 min. Measure corporate IP false positives. Tune from real telemetry, not spreadsheet only.
Calibrate without punishing
Start with 14-day baseline: p50/p95/p99 per endpoint and API key. Set limit at 2× p99 of largest legit client on expensive endpoint.
Implement token bucket with 2× sustained burst. Announce headers before enforce.
Create low "sandbox" tier for dev keys and contractual "production" tier. Overselling without documented quota = support tickets.
Watch 429 rate: if >1% legit requests, limit too low. If scraper unchanged, limit mis-targeted (IP vs key).
Revise after each major client onboarded — their traffic profile shifts median for everyone if poorly isolated.
Size with real numbers
Export seven days of access logs: count requests per minute per API key and route. Global limit "1000 req/min" hides an /export endpoint generating 800 alone. Limit sensitive routes: auth, search, export, inbound webhook.
Polite crawlers (Googlebot) vs aggressive scrapers: IP-only rate limit punishes the former behind corporate NAT. Combine behavior (missing User-Agent, suspicious endpoint sequence) with key quota.
Communicate migration calendar: "Limit enforced from October 1" with preview headers before hard block. Partner SDKs integrate Retry-After; homemade scripts do not — warn them.
On small budget VPS, local Redis for counters suffices until a few thousand req/s. Beyond that, edge CDN rate limit prevents the counter becoming your own Redis DDoS.
B2B partners often ask for "no limit" — answer with contracted numeric quota + burst + overage price, not absence of limit.
Separate 429 technical vs 402 billing: mixing both in same API doc creates endless support tickets.
Dashboard graph: top consumers per key — identify authenticated scrapers before they become security incidents.
Partner communication template
Email partners 30 days before limit enforcement with headers example and Retry-After handling code snippet.
Offer temporary raised quota during migration window — contractual clarity.
Monitor 429 per API key dashboard shared with customer success for proactive outreach.
Operational summary
Rate limits protect origin and ensure fairness — token bucket per API key, documented quotas, 429 plus Retry-After headers. Edge plus app layers harmonized. Measure baseline before enforcing limits on partners.
Keep a dated runbook, before/after metrics, post-incident review — cumulative discipline beats Friday night panic.
Keep a dated runbook, before/after metrics, post-incident review — cumulative discipline beats Friday night panic.
Keep a dated runbook, before/after metrics, post-incident review — cumulative discipline beats Friday night panic.
Keep a dated runbook, before/after metrics, post-incident review — cumulative discipline beats Friday night panic.
Keep a dated runbook, before/after metrics, post-incident review — cumulative discipline beats Friday night panic.
Keep a dated runbook, before/after metrics, post-incident review — cumulative discipline beats Friday night panic.
Edge rate limit
Local Redis VPS then CDN edge beyond thousands req/s.
Decide and move forward without blind spots
- Measure fourteen days baseline — p50/p95/p99 per endpoint and API key.
- Set limit at 2× p99 of largest legitimate client on the most expensive endpoint.
- Token bucket with burst — announce RateLimit headers before enforcement.
- Sandbox and production tiers — documented contractual quotas to avoid support tickets.
- Review after each major client — traffic profile shifts the median for everyone if poorly isolated.
Size CPU and network via our directory, comparison tool, and API blog notes.
Frequently asked questions
Is IP limiting enough?
Not for NAT or CDN clients. Prefer API key + IP fallback with per-tenant quotas.
Token bucket or fixed window?
Token bucket smooths bursts. Fixed window cliff-effects at window end; sliding window costs more but is fairer.
Which headers to return?
429 + Retry-After + X-RateLimit-Remaining/Limit/Reset helps SDKs backoff cleanly.
Rate limit at edge or app?
Edge stops floods early. App keeps fine business limits (cost per endpoint).
Publish limits in docs before the next launch — good clients plan, bots do not.