What Is API Rate Limiting? – Definition and How It Works
Learn what API rate limiting is, the algorithms behind it, the headers that describe your budget, and how clients should behave when limited.
Rate limiting caps how many requests a caller may make in a period. It protects capacity, keeps one noisy client from degrading service for everyone, and turns an implicit resource into an explicit, purchasable quantity.
1. What Is Rate Limiting?
It is a policy applied per identity — an API key, an account, an address, or an endpoint.
- Key idea: requests consume a budget that refills over time.
- Mechanism: a counter per identity and window, enforced before the request does real work.
- Goal: predictable capacity and fair distribution among callers.
2. The Common Algorithms
| Algorithm | Behaviour | Trade-off |
|---|---|---|
| Fixed window | N requests per clock interval | Bursts cluster at window edges, allowing 2N across a boundary |
| Sliding window | Counts over a rolling period | Smoother, more state to maintain |
| Token bucket | Tokens refill steadily, requests spend one | Allows controlled bursts; the common default |
| Leaky bucket | Requests drain at a constant rate | Strictly smooth output, queues instead of bursting |
Token bucket is the most widely used because it tolerates short bursts while bounding the sustained rate.
3. How the Limit Is Communicated
Well-behaved APIs publish the state of your budget in response headers:
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1767225600
When the budget is exhausted the response is 429 Too Many Requests, ideally with Retry-After naming how long to wait. A client that reads these headers can pace itself instead of discovering the limit by hitting it.
4. What Gets Limited
- Per key or account — the usual unit, tied to a plan.
- Per endpoint — expensive operations get tighter budgets than cheap ones.
- Per address — protects unauthenticated surfaces.
- Concurrency — a separate cap on simultaneous in-flight requests, which is distinct from a rate.
Hitting a concurrency cap while well under a rate limit is common and confusing if only the rate is being tracked.
5. How a Client Should Behave
- Read the limit headers and stay under the budget rather than probing it.
- Treat
429as instruction, not failure — honourRetry-After. - Spread load evenly instead of bursting at the start of each window.
- Cache responses that do not change often, since the cheapest request is the one not made.
- Distinguish a rate limit from a quota: one refills, the other is a period allowance that does not.
6. Why Limits Vary Unexpectedly
- Limits are often per endpoint, so one call succeeding says nothing about another.
- Shared egress means several clients behind one address can exhaust an address-based limit together.
- Plans change budgets, and some services apply dynamic limits under load.
- Some APIs count cost units rather than requests, so a heavy call consumes more of the budget.
7. Common Misconceptions
- "429 means blocked." It means slow down; the budget refills.
- "Rate limit and quota are the same." A rate is per second or minute; a quota is per month and does not refill until it resets.
- "More parallelism means more throughput." Beyond the concurrency cap it means more errors.
- "Limits are documented accurately." Published figures are a floor for planning; observed headers are the truth for a given key.
8. Summary
Rate limiting bounds request rate per identity, usually with a token bucket, and communicates the remaining budget in response headers with 429 and Retry-After when exhausted.
A well-behaved client reads the headers, paces itself under the limit, caches what it can, and treats the limit as a published part of the contract rather than an obstacle to discover empirically.