An API rate limit is a cap an API sets on how many requests a client may make within a given time window, rejecting or delaying requests that exceed it to protect the service from overload and abuse. When you cross the limit, the API typically responds with the 429 Too Many Requests status and often tells you when you can try again. Rate limits keep shared services fair and stable, and handling them gracefully with backoff and retries is a core skill for building reliable API clients.
Key takeaways
- A rate limit caps requests per client over a time window to protect and share capacity.
- Exceeding it usually returns HTTP
429 Too Many Requests. - The
Retry-Afterheader, when present, tells you how long to wait. - Common algorithms include token bucket, leaky bucket, fixed window, and sliding window.
- Clients should retry with exponential backoff and jitter, never in a tight loop.
- Rate-limit headers let you track remaining quota before you hit the wall.
Why do APIs enforce rate limits?
Rate limits exist to keep a shared service healthy and equitable. Without them, a single misbehaving client, a runaway script, or an attacker could consume all available capacity and degrade the experience for everyone.
- Stability: prevent traffic spikes from overwhelming servers and databases.
- Fairness: ensure no one client monopolizes shared capacity.
- Cost control: bound the compute and bandwidth the provider must pay for.
- Security: blunt brute-force, scraping, and denial-of-service attempts.
- Monetization: differentiate service tiers by allowed request volume.
What happens when you exceed a rate limit?
When you go over, the server rejects the request rather than processing it. The standard signal is the 429 Too Many Requests status, frequently accompanied by a Retry-After header and a body explaining the limit.
HTTP/1.1 429 Too Many Requests
Retry-After: 30
Content-Type: application/json
{ "error": "rate_limit_exceeded", "message": "Try again in 30 seconds" }The correct response is to stop sending, wait the indicated time, and only then retry. Some APIs also use 503 Service Unavailable with Retry-After under heavy load, which you handle the same way.
It is worth distinguishing a rate-limit rejection from other failures. A 429 means your request was well-formed and would normally succeed; you simply asked too often, so retrying after a wait is the correct response. By contrast, a 400 or 404 signals a problem with the request itself that retrying will not fix. Treating these categories differently is what separates a resilient client from one that hammers a struggling service with pointless retries.
What algorithms are used for rate limiting?
Providers implement rate limiting with several well-known algorithms, each with different burst behavior.
| Algorithm | How it works | Burst behavior |
|---|---|---|
| Fixed window | Counts requests per fixed interval | Allows spikes at window edges |
| Sliding window | Counts over a rolling interval | Smoother than fixed window |
| Token bucket | Tokens refill at a set rate; each request spends one | Permits bursts up to bucket size |
| Leaky bucket | Requests drain from a queue at a steady rate | Enforces a smooth output rate |
Token bucket is popular because it allows short bursts while still enforcing a steady average, which matches how real clients behave. Fixed window is simple but can let twice the intended traffic through around a boundary if requests cluster at the end of one window and the start of the next.
How do you read rate-limit headers?
Rather than waiting to be rejected, well-behaved clients track their remaining quota using headers many APIs return on every response. Common conventions include a limit, a remaining count, and a reset time.
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 12
X-RateLimit-Reset: 1700000000Here you may make 100 requests per window, have 12 left, and the window resets at the given timestamp. A standardized RateLimit header format also exists, so check the specific API’s documentation because header names and the meaning of the reset value vary between providers.
How should clients handle rate limits gracefully?
Robust clients treat limits as a normal condition, not an error to ignore. The essential pattern is exponential backoff with jitter.
- On a
429, readRetry-Afteror the reset header and wait at least that long. - If no delay is given, back off exponentially, doubling the wait after each failure.
- Add random jitter so many clients do not retry in sync and cause a new spike.
- Cap the maximum wait and the number of retries so requests do not hang forever.
async function requestWithRetry(fn, maxRetries = 5) {
for (let attempt = 0; attempt <= maxRetries; attempt++) {
const res = await fn();
if (res.status !== 429) return res;
const retryAfter = Number(res.headers.get("Retry-After")) || 2 ** attempt;
const jitter = Math.random();
await new Promise((r) => setTimeout(r, (retryAfter + jitter) * 1000));
}
throw new Error("Rate limit: retries exhausted");
}What scopes and tiers do rate limits apply to?
A frequent surprise is discovering that an API has not one limit but several, applied at different scopes and often stacked. Reading the documentation to learn exactly what is being counted saves hours of confusion when requests are rejected even though you seem to be well under a limit.
Common scopes include:
- Per API key or token. The most common scope, tying the quota to your credentials regardless of source IP.
- Per user. Limits applied to an authenticated end user, so one abusive account cannot exhaust the quota for others.
- Per IP address. Often used for unauthenticated endpoints and as an anti-abuse baseline.
- Per endpoint or method. Expensive operations such as search or bulk writes may have tighter limits than cheap reads.
On top of scope, providers usually define tiers, where free plans get lower limits than paid plans, and some enforce both a short-term burst limit and a longer-term quota at the same time. For example, an API might allow a certain number of requests per second while also capping total requests per day.
| Window | Purpose |
|---|---|
| Per second or minute | Smooths bursts and protects capacity moment to moment |
| Per hour or day | Bounds total consumption and enforces plan quotas |
Because these limits combine, a client can satisfy the per-second rule yet still be blocked for exceeding a daily quota. Track each relevant limit separately, and when in doubt inspect the rate-limit headers, which usually report the specific limit that applies to the request you just made.
How can you avoid hitting rate limits in the first place?
Prevention is better than recovery. Several strategies reduce how often you brush against a limit:
- Cache responses so you do not re-request data that has not changed.
- Batch requests where the API supports combining multiple operations into one call.
- Use webhooks or streaming instead of polling frequently for changes.
- Throttle client-side by spacing requests to stay under the known limit.
- Respect remaining-quota headers and slow down proactively as you approach zero.
What are common rate-limiting mistakes?
- Retrying immediately on a 429. A tight retry loop amplifies the overload and can extend penalties.
- Ignoring
Retry-After. Guessing a delay instead of using the provided one wastes requests. - No jitter. Synchronized retries from many clients create repeated thundering-herd spikes.
- Assuming one global limit. Limits often differ per endpoint, per method, per user, and per IP; read the docs.
- Not distinguishing 429 from other errors. Rate-limit responses need backoff, while a
400should not be retried unchanged.
Frequently asked questions
What HTTP status code means I hit a rate limit?
The 429 Too Many Requests status indicates you exceeded the allowed rate. The response often includes a Retry-After header telling you how long to wait before trying again.
What is the Retry-After header?
Retry-After tells the client how long to wait before making another request, given either as a number of seconds or an HTTP date. Respect it instead of retrying immediately.
What is the difference between rate limiting and throttling?
Rate limiting sets a hard cap and rejects requests beyond it, while throttling more generally slows or shapes traffic. In practice the terms are often used interchangeably.
How should a client handle a 429 response?
Stop, read Retry-After or the reset header, and retry after that delay using exponential backoff with jitter. Never retry instantly in a tight loop, which makes the problem worse.
Why do APIs use rate limits?
To protect the service from overload and abuse, ensure fair capacity across clients, control cost, and defend against denial-of-service and brute-force attacks.
What is a token bucket?
A token bucket holds tokens that refill at a steady rate; each request spends one token. It permits short bursts up to the bucket size while enforcing an average rate over time.
How do I know my current rate-limit status?
Many APIs return headers such as a limit, remaining, and reset value on each response, letting you track how many requests you have left and when the window resets.