TapCub is live — analytics, insights and live chat, free on one platform
Glossary

What is API rate limiting? 429 errors, Retry-After and backoff

API rate limiting caps how many requests a client can send in a period. What gets counted, how limits are enforced, what 429 and Retry-After mean, and how to pace and retry without making it worse.

Chen Yu Reviewed by Ethan Brooks Also called rate limiting Last updated Nov 17, 2026 Glossary

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:

MeterExample limitWhat it means for the client
Number of operations20 requests per secondFewer requests help; request size does not matter
Amount of data2 GiB per minuteSmall requests are fine; big payloads count
Cost of operations20,000 request units per secondAn 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

MethodHow it countsBehaviour to expect
Fixed windowRequests per clock window, such as per minute, reset at the boundarySimple, 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 windowRequests in the last 60 seconds, measured from nowNo boundary burst; the limit feels smoother
Token bucketEach request takes a token; tokens refill at a steady rate; the bucket size is the largest burstShort bursts are allowed, sustained speed is capped. Stripe describes this as the core of its request rate limiter
Concurrency limitThe number of requests in progress at onceSlow 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

  1. Do not retry immediately. The window is still full, so an instant retry is rejected and adds load.
  2. Wait as long as the server says. If Retry-After (or an equivalent field) is present, wait at least that long.
  3. 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.
  4. Cap the retries. After a handful of attempts, give up and surface the error.
  5. Retry only what can heal. A 429, a 5xx and a network error can succeed later; most other 4xx cannot.
  6. 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.

RetryMaximum wait windowAverage wait with full jitter (half the window)
11 s0.5 s
22 s1 s
34 s2 s
48 s4 s
516 s8 s
632 s16 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.

StrategyRequests sentRejectedTime to finish
Send everything, retry whatever failed every minute1,000 + 900 + 800 + … + 100 = 5,5005,500 − 1,000 = 4,50010 minutes
Send 100 per minute from the start1,000010 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 retryAfter fails eleven more times.
  • Retrying permanent failures. A 400, 401 or 403 will not turn into a 200 after 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.

  1. 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.
  2. 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.
  3. Handle a 429. The response has code set to RATE_LIMIT and a retryAfter value in seconds. Wait at least that long, then resend the same batch with the same insert_id values, since duplicates from retries are deduplicated on insert_id. Branch on code, not on message, which may be in Chinese.
  4. 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, 5xx and 429 up to 5 times, starting at 0.5 seconds and doubling to at most 30 seconds, and they honour Retry-After. Other 4xx responses are not retried. Up to 10,000 events wait in memory; beyond that the oldest are dropped and reported as QUEUE_FULL.
  5. 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 no 429 to 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 return 202 and 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

Was this explanation clear?

We use your answers to fix and expand this page.

Chen Yu

Technical Engineer

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

FAQ

Questions people ask

Short answers to the follow-up questions that come up most.

Still have a question?

Chat with the team behind TapCub — we usually reply within a few hours on business days.

What does HTTP 429 Too Many Requests mean?

It means the client has sent too many requests in a given amount of time. The response may carry a Retry-After header saying how long to wait. The standard leaves it to each server to decide how it identifies the client and counts requests.

How long should I wait after a 429?

At least as long as Retry-After (or the equivalent field in the response body) says. With no hint, back off exponentially with random jitter, cap the number of retries, and give up after a handful of attempts.

What is the difference between rate limiting and throttling?

Usage differs by source. In Microsoft's terms, throttling is what a service does to requests it will not serve at full speed, and the rate-limiting pattern is the client pacing its own requests to stay under those throttling limits.

What are TapCub's server event limits?

The server events endpoint allows 600 requests per minute per API key, with up to 1,000 events per request. Over the limit, it returns 429 with code RATE_LIMIT and a retryAfter value in seconds.

See this number on your own site

Add one script tag for web and apps, and the first reports fill in within minutes.

See your data clearly. Find your growth.

Every click, backed by data. Install one line of code and see your first numbers in a minute.

No credit card · Free plans for analytics and chat · Cookieless analytics