Rate-Limiting

A bucket of capacity three begins full. Three unit-cost admissions at time zero empty it immediately; a fourth is denied. At half a second, refill at two tokens per second provides one token. Three states show burst spending followed by elapsed-time refill, without promising paced departures.

A token bucket bounds admission and allows bursts

A token bucket bounds admitted work while allowing accumulated credit to be spent in a burst. It does not automatically space requests evenly, guarantee completed throughput, or cap the number of operations still running. Those are separate scheduling and capacity questions. The bucket’s two parameters describe a budget, not a promise that the service can perform it. ...

A received three-second wait creates an earliest retry boundary; nonnegative jitter places planned attempts after it. A deadline can stop the policy.

Retry-After tells when to try again

Retry-After tells a client how long it ought to wait before a follow-up request. It is a scheduling signal, not proof that the next attempt will succeed or that replaying the original operation is safe. A client still needs a deadline, an attempt policy, and a decision about which operations it can retry. ...

Rate limiting needs a stable client identifier

A rate-limit key defines which requests share a budget. An account, API credential, address, tenant, and authenticated session are different identities, not interchangeable spellings of “client.” Choosing the wrong grouping can punish unrelated users or let one workload obtain fresh allowance simply by changing a field. ...

Sixteen independent callers each invoke a separate atomic Lua admission script on the same shared budget key. The script compares the limit, then creates the counter with expiry or increments it when admission is allowed. Five admitted and eleven denied are aggregate outcomes across the sixteen calls for a budget of five. This is the article fixture, not a newly executed Redis result.

Rate limiting is a shared budget

A rate limit is a budget for admitted work, defined by its unit, identity, scope, and time rule. “Five requests” is incomplete without saying whose requests, across which endpoints and workers, during which interval, and what happens after exhaustion. A shared counter helps only when every relevant admission uses the same authoritative decision. ...