What Is Rate Limiting? How It Works and How to Handle It
Every serious API caps how fast you can call it. Here's how rate limits work, the algorithms behind them, and how to build a client that handles a 429 without falling over.
Rate limiting vs throttling
|
Rate limiting |
Throttling | |
|---|---|---|
|
What happens to excess requests |
Rejected |
Slowed down or queued |
|
Typical response |
HTTP 429 with Retry-After |
Delayed response, or 429 once the queue is full |
|
Main goal |
Hard cap to protect the service and enforce plan limits |
Smooth bursts into a steady rate |
|
Client experience |
Must back off and retry |
Requests succeed, just later |
|
Common algorithm |
Fixed or sliding window, token bucket |
Leaky bucket |
|
Example |
500 API calls a minute on a free plan |
Sending queued emails at 10 per second |
How rate limiting works
The service identifies who is calling, usually by API key, user ID or IP address, and counts their requests over a time window. Each new request is checked against the limit. Under it, the request goes through. Over it, the service refuses the request without doing the work.
Well-behaved APIs tell you where you stand. Responses typically carry headers such as the limit, the requests left in the current window and when the window resets. When you go over, you get HTTP 429 Too Many Requests, defined in RFC 6585, often with a Retry-After header saying how many seconds to wait.
Limits usually apply at more than one level: per app or account, per user, and per endpoint. A sending endpoint might have a tighter cap than a read endpoint, because it costs more and is the one spammers target.
Rate limiting algorithms
Fixed window
Count requests in fixed blocks, such as each calendar minute, and reset the counter at the boundary. It's simple and cheap to run. The weakness is the edge: a client can send a full quota at 12:00:59 and another at 12:01:00, doubling the rate for a moment.
Sliding window
Look back over the last 60 seconds from now, instead of the current calendar minute. A sliding log stores each request's timestamp and is exact but memory-hungry. A sliding counter blends the current and previous window's counts to approximate it cheaply, which is what most large systems use.
Token bucket
Each client has a bucket holding up to N tokens, refilled at a steady rate. Every request spends a token; an empty bucket means the request is rejected. This allows short bursts up to the bucket size while holding the long-run average to the refill rate.
Leaky bucket
Requests join a queue that drains at a fixed rate, like water through a hole. Bursts are smoothed into a constant output, and requests are dropped only when the queue overflows. It's closer to throttling than to rejection.
How to handle a 429 in your client
Retrying immediately makes things worse: every rejected client hammering the API at once is how short spikes turn into outages. Wait, then retry with exponential backoff and a little randomness (jitter):
async function callWithRetry(url, options, attempt = 0) {
const res = await fetch(url, options);
if (res.status !== 429 || attempt >= 5) return res;
const retryAfter = Number(res.headers.get('Retry-After'));
const base = retryAfter > 0 ? retryAfter * 1000 : 1000 * 2 ** attempt;
const wait = Math.min(base + Math.random() * 500, 5 * 60 * 1000);
await new Promise((r) => setTimeout(r, wait));
return callWithRetry(url, options, attempt + 1);
}
Better still, avoid hitting the limit at all. Read the remaining-requests header and slow down as it approaches zero, batch work where the API supports it, and cache responses that don't change often.
Rule of thumb: treat Retry-After as an instruction, not a hint. Wait at least that long, then back off exponentially if you get another 429.
Why services rate limit
Stability. A single runaway script can't consume capacity meant for everyone else.
Abuse prevention. Login, signup and messaging endpoints are limited to slow down credential stuffing and spam.
Cost control. Expensive operations, from AI model calls to SMS sends, get tighter caps.
Fair plans. Free and paid tiers get different limits, so heavy users move to a plan that funds their usage.
Limits and pitfalls
Retry storms. Clients that retry without backoff turn a short limit into a sustained one. Always honour Retry-After.
Shared IPs. Limiting by IP address can block a whole office or mobile carrier behind one address. Prefer API keys or user IDs.
Distributed counting. With many servers, counters need a shared store such as Redis, or each server enforces only part of the limit.
Silent limits. If an API returns 429 without headers, log every occurrence so you can learn its real limits.
Background jobs. Bulk imports and migrations are the usual way teams hit limits. Spread them out or ask the provider about a dedicated bulk endpoint.
CometChat's rate limits
CometChat publishes its REST API limits, so you can plan around them instead of discovering them in production.
The numbers, and what to do above them
Core operations (connecting users, creating and deleting users, creating, joining and leaving groups) are limited to 10,000 requests a minute, and standard operations such as sending messages and updating profiles to 20,000 a minute. The free Build plan allows 500 requests a minute across both. Each user can send 30 messages a minute, and bulk data import runs at 60 requests a minute. Over a limit, the API returns HTTP 429 with the error code
ERR_TOO_MANY_REQUESTSand aRetry-Afterheader.Above the limit, back off: start with the Retry-After value, double the wait after each further 429 and cap it at five minutes, as the docs recommend. Track the remaining-requests header to slow down before you hit the cap. Limits can be adjusted for your use case and plan, so if your workload needs more, contact CometChat.
Frequently asked questions
What does 'rate limit exceeded' mean?
You sent more requests than the service allows in its current time window. Wait for the period in the Retry-After header, or until the window resets, then try again.
What is HTTP 429?
429 Too Many Requests is the status code a server returns when a client has been rate limited. It's defined in RFC 6585 and often comes with a Retry-After header.
What is the difference between rate limiting and throttling?
Rate limiting rejects requests over a cap. Throttling slows them down or queues them so they're processed at a steady rate. Many systems use both.
Which rate limiting algorithm is best?
Token bucket is the most common choice for APIs because it allows short bursts while holding the average rate. Sliding window counters are a good alternative when you need even enforcement at window edges.
How do I avoid hitting API rate limits?
Read the rate-limit headers and slow down before you reach zero, batch requests, cache responses that rarely change, and spread bulk jobs over time.