The token bucket rate limiter calculator gives the time before the bucket empties, the share of rejected requests, the refill time and the most requests allowed in a time window, from the refill rate, the capacity and the incoming rate.
How the calculation works
- Enter the refill rate and the bucket capacity.
- Enter the incoming request rate and the time window.
- The calculator gives the time to empty, the rejected share, the accepted throughput, the refill time, the requests in the window and the burst.
Example
A limiter refills 100 tokens per second into a bucket of 200. A client sends 150 requests per second, so the bucket loses 50 tokens a second and is empty after 200 / 50 = 4.00 s. Then only 100 requests per second pass, so 33.3 % are rejected. An empty bucket needs 2.00 s to refill, and in 10 s at most 200 + 100 × 10 = 1,200 requests can be accepted.
Why it matters
The calculator helps API designers, backend developers and operators to choose the limits of a public API, a login endpoint or a message queue, and to explain the behavior to clients.
Good to know
The same algorithm shapes network traffic: routers use it to police or shape a link, with the capacity acting as the committed burst size. A client that stays below the refill rate never sees a rejection, whatever the burst, as long as bursts are shorter than the capacity allows. Choosing the capacity is a balance: a larger bucket is kinder to bursty but legitimate clients and a smaller one protects the servers better. Rejected requests should get a clear error with a hint about when to retry, and clients should back off with some randomness. Limits are often applied per key or per address, so the numbers here are for one client. Distributed limiters need shared counters and may be approximate.
Related tools
The queue wait time calculator covers waiting lines, the server capacity calculator sizes servers, the network latency calculator explores delays and the VoIP bandwidth calculator shows another traffic planning case.