API Rate Limiter Calculator: Token Bucket Math
Rate limit headers like '100 requests per minute, burst 100' describe a token bucket — but translating that into 'how long can I burst at this rate before getting throttled' or 'is my polling interval actually safe long-term' takes a bit of arithmetic. This calculator does that math directly.
When desiredRate ≤ refillRate, the bucket never fully drains — the rate is sustainable indefinitely.
How a Token Bucket Actually Works
Picture a bucket that holds up to `burstCapacity` tokens, continuously refilling at `refillRate` tokens per second. Every request consumes one token; if the bucket is empty, the request is rejected or delayed. This lets a client burst above the steady-state rate briefly (up to the bucket's capacity) while still enforcing a long-term average rate.
Why the Formula Only Applies When Rate Exceeds Refill
If your request rate is at or below the refill rate, tokens are added back at least as fast as you're spending them — the bucket level never trends toward zero, so there's no 'exhaustion' to calculate. The exhaustion formula only makes sense once your consumption rate outpaces replenishment.
Designing Around a Known Rate Limit
Knowing the steady-state interval (time between individually allowed requests once burst is spent) tells you the safe polling interval for sustained, long-running usage — while the burst capacity tells you how much slack you have for a short traffic spike before that steady-state limit kicks in.
Practical Examples
Checking a Polling Interval
An API allows 100 req/min with burst 100; you want to poll at 5 req/s.
- 1.Limit: 100, Window: 60s, Burst: 100, Desired: 5 req/s
- 2.Result: not sustainable — burst exhausted after ~24s, then throttled to the steady rate
What Gets Calculated
- Refill rate (tokens/requests per second)
- Whether a desired rate is sustainable long-term
- Time until burst capacity is exhausted (if not sustainable)
- Steady-state interval between allowed requests
Good Use Cases
- Sizing a safe polling interval against a known API rate limit
- Understanding how long a burst of requests can run before throttling
- Explaining rate-limit behavior to a team designing an integration
- Sanity-checking your own rate limiter's configuration
Frequently Asked Questions
What is the token bucket algorithm?
A rate-limiting model where a bucket holds up to a fixed number of tokens (the burst capacity), refilling continuously at a steady rate; each request consumes one token, and requests are only allowed while tokens are available. It's the algorithm behind most 'X requests per window, with burst allowance' API rate limits.
What does 'sustainable indefinitely' mean here?
If your desired request rate is at or below the bucket's refill rate, you'll never fully drain the bucket — the token supply replenishes at least as fast as you consume it, so you can maintain that rate forever without hitting the limit.
What happens after the burst is exhausted?
Once the bucket empties, you're limited to the steady-state refill rate — each additional request beyond that rate has to wait for a new token to become available, spaced roughly by the steady-state interval shown.
How does burst capacity relate to the rate limit window?
Burst capacity is often set equal to the window's request limit (e.g., '100 requests per minute' implies a 100-token bucket refilling over 60 seconds), but many real APIs configure a separate, often larger burst allowance to smooth out legitimate traffic spikes without changing the sustained long-term rate.
Does this match how my specific API's rate limiter actually works?
Token bucket is the most common model, but not universal — some APIs use fixed windows (a hard reset every N seconds) or sliding-window counters instead, which behave slightly differently at window boundaries. Check your API provider's documentation for their exact algorithm.