Quick answer
API rate limiting is a cap, enforced by the server, on how many requests a client may send in a given period. Requests over the cap are refused, usually with HTTP 429 Too Many Requests, and the client is expected to wait before trying again.
Formula: Wait before retry = random(0, min(cap, base × 2^attempt))
What is API rate limiting?
API rate limiting is a cap on how many requests a client can send to an API in a given period, enforced by the server. When a client goes over the cap, the server refuses the extra requests, usually with the HTTP status 429 Too Many Requests, and accepts new ones once the period rolls over or capacity returns. The limit protects the server from overload and stops one heavy client from using up capacity that other clients share.
For the person calling the API, the useful reading is this: a limit is a rule about pace, not a failure. A well-behaved client expects to hit it sometimes, waits the time it is told to wait, and sends fewer, larger requests where it can.
What gets counted
Services meter different things. Microsoft's rate-limiting pattern lists three common ones:
| Meter | Example limit | What it means for the client |
|---|---|---|
| Number of operations | 20 requests per second | Fewer requests help; request size does not matter |
| Amount of data | 2 GiB per minute | Small requests are fine; big payloads count |
| Cost of operations | 20,000 request units per second | An expensive query uses more of the budget than a cheap one |
The second question is who "the client" is. The HTTP specification for 429 deliberately does not say: it leaves it to the server how to identify the user and how to count requests. In practice the counter is attached to an API key, a user ID, an IP address, or a mix. That choice matters. A limit per key follows your credentials no matter how many machines you run, while a limit per IP can catch everyone behind the same office network.
Common ways limits are enforced
| Method | How it counts | Behaviour to expect |
|---|---|---|
| Fixed window | Requests per clock window, such as per minute, reset at the boundary | Simple, but allows a burst across the boundary: 100 requests at 12:00:59 and 100 more at 12:01:00 is 200 in two seconds under a 100-per-minute limit |
| Sliding window | Requests in the last 60 seconds, measured from now | No boundary burst; the limit feels smoother |
| Token bucket | Each request takes a token; tokens refill at a steady rate; the bucket size is the largest burst | Short bursts are allowed, sustained speed is capped. Stripe describes this as the core of its request rate limiter |
| Concurrency limit | The number of requests in progress at once | Slow requests hold a slot; sending faster does not help |
The service rarely tells you which one it uses. Treat the published number as the sustained rate, and do not rely on a burst being allowed.
What a limited response looks like
RFC 6585 defines 429: the user has sent too many requests in a given amount of time. The response may include a Retry-After header saying how long to wait. Per RFC 9110, Retry-After carries either a number of seconds or an HTTP date, for example Retry-After: 120 means two minutes. The header is optional, so a client must also work without it.
Some APIs put the wait in the JSON body instead, along with a machine-readable code. Branch on the code, not on the human-readable message.
A 429 is different from a 5xx. A 429 says "you are going too fast"; a 500-class error says "something broke on our side". Both are worth retrying after a wait. Most other 4xx responses, such as a malformed body or a bad key, will fail again the same way.
How a client should react
- Do not retry immediately. The window is still full, so an instant retry is rejected and adds load.
- Wait as long as the server says. If
Retry-After(or an equivalent field) is present, wait at least that long. - Without a hint, back off exponentially, with jitter. Double the maximum wait on each attempt up to a cap, then pick a random delay up to that maximum. AWS's analysis of retrying clients found that adding jitter cut the number of calls by more than half with 100 competing clients, because clients stop retrying in lockstep.
- Cap the retries. After a handful of attempts, give up and surface the error.
- Retry only what can heal. A
429, a5xxand a network error can succeed later; most other4xxcannot. - Reuse the same idempotency key on a retry, so a request that actually went through is not counted twice.
Sample schedule: base 1 second, cap 60 seconds, six attempts.
| Retry | Maximum wait window | Average wait with full jitter (half the window) |
|---|---|---|
| 1 | 1 s | 0.5 s |
| 2 | 2 s | 1 s |
| 3 | 4 s | 2 s |
| 4 | 8 s | 4 s |
| 5 | 16 s | 8 s |
| 6 | 32 s | 16 s |
The longest possible total wait is 1 + 2 + 4 + 8 + 16 + 32 = 63 seconds; on average, 31.5 seconds.
A worked example: pacing beats blind retry
Sample data: a job has 1,000 requests to send to an API limited to 100 per minute. Assume fixed one-minute windows, and that the client retries at the start of the next window.
| Strategy | Requests sent | Rejected | Time to finish |
|---|---|---|---|
| Send everything, retry whatever failed every minute | 1,000 + 900 + 800 + … + 100 = 5,500 | 5,500 − 1,000 = 4,500 | 10 minutes |
| Send 100 per minute from the start | 1,000 | 0 | 10 minutes |
Both strategies finish in ten minutes, because the limit sets the speed. The blind one sends 5.5 times the traffic to get there, and every rejected request also has to be logged and handled. Batching is the other lever: if the same API accepts up to 50 records per request, the same 1,000 records are 20 requests, which fit in a single minute.
Pacing has a cost, which is delay. The data lands later than it would without a limit, so work out how long a backfill will take before you start it. See data latency.
Limits that never return a 429
Not every limit announces itself. Some endpoints that receive traffic from browsers drop the excess and still answer with a success status, because the sender cannot do anything useful with an error. That makes a 2xx a statement about the request, not about what was kept.
A rate limit also differs from a quota. A rate limit is per short window and recovers by itself in seconds or minutes. A quota, such as a monthly event allowance, is per billing period and recovers only when the period resets or the plan changes. If requests succeed but data is missing, check the quota and the reports before you blame the rate.
Common mistakes
- A retry loop with no delay. It turns one rejected request into a flood.
- One request per record. Where an endpoint takes a batch, a thousand single requests spend a thousand units of a request limit; one batch spends one.
- Ignoring the wait the server gave you. A fixed one-second sleep against a 12-second
retryAfterfails eleven more times. - Retrying permanent failures. A
400,401or403will not turn into a200after a wait. - Several workers sharing one key without sharing a limiter. Each worker stays under the limit, and the total does not. Route all workers through the same pacing mechanism.
- Retrying without an idempotency key. A request that actually succeeded is counted twice.
Rate limits in TapCub
Suppose you want to backfill 120,000 historical orders from your database into TapCub through the server events endpoint.
- Create a key. In Configuration › Settings › API keys, create a key with the Server track scope. The key starts with
wck_and is shown once. - Do the arithmetic first. Server behavior events (
/api/v1/track) allow 600 requests per minute per key, with up to 1,000 events per request, and a request body of at most 2 MB. One event per request would be 120,000 requests ÷ 600 = 200 minutes, about 3.3 hours. In batches of 1,000 it is 120 requests, a fifth of one minute's allowance. - Handle a
429. The response hascodeset toRATE_LIMITand aretryAftervalue in seconds. Wait at least that long, then resend the same batch with the sameinsert_idvalues, since duplicates from retries are deduplicated oninsert_id. Branch oncode, not onmessage, which may be in Chinese. - Or let a server SDK do it. The server SDKs queue events and send them every 3 seconds or when 200 are queued, with at most 1,000 events and 1 MB per request. They retry network errors,
5xxand429up to 5 times, starting at 0.5 seconds and doubling to at most 30 seconds, and they honourRetry-After. Other4xxresponses are not retried. Up to 10,000 events wait in memory; beyond that the oldest are dropped and reported asQUEUE_FULL. - Remember that browser collection works differently. Pageviews from the website script are limited per visitor, IP and site. Excess events are dropped silently and the collector still returns
202, so there is no429to react to. Open Web analytics › Realtime to see whether your events arrived. Note that a monthly event quota is separate: after the cap, collect requests still return202and events are not stored.
See also: What is basic authentication? How the header works and when to avoid it.
See also: Brute Force Attack: How It Works and How to Prevent It.
See also: Smurf Attack: How It Works and Why It Is Rare Now.
Sources
- IETF, RFC 6585, Additional HTTP Status Codes, section 4: 429 Too Many Requests.
- IETF, RFC 9110, HTTP Semantics, section 10.2.3: Retry-After.
- Microsoft Azure Architecture Center, Rate Limiting pattern.
- Stripe, Scaling your API with rate limiters.
- AWS Architecture Blog, Exponential Backoff And Jitter.
Was this explanation clear?
We use your answers to fix and expand this page.
Couldn’t send. Please try again in a minute.
Thanks for the feedback. We’ll use it to improve this page.You’ve already sent feedback on this page. Thanks.

Technical Engineer
Focuses on tracking code, SDKs, and API integrations, with practical guidance on implementation checks and troubleshooting.