Hong Life CalculatorsUnderstanding the API rate limit and token bucket calculator — concept and principle
Most APIs limit how fast clients may call them, and the token bucket is the most common way to express that limit: a short burst is allowed, then requests must slow to a steady rate. This calculator tells you the minimum time needed to send a batch of requests under a given refill rate and bucket size, and how many requests the steady rate allows per day. It helps when planning bulk jobs, data migrations and client-side throttling.
How it is calculated
- Minimum time (s) = max(0, (requests − bucket size) ÷ refill rate).
- Requests per day = refill rate × 86,400 (seconds in a day).
The bucket is assumed to start full. Refill rate is in requests per second; bucket size is the maximum burst.
The principle
Picture a bucket holding up to B tokens, refilled at r tokens per second. Each request spends one token; if the bucket is empty, the request must wait (or is rejected, typically with HTTP 429 Too Many Requests). Starting full, you can send B requests immediately. Every further request needs a new token, and tokens arrive at rate r, so the remaining N − B requests take (N − B) ÷ r seconds. Over long periods the burst becomes negligible and throughput approaches r. A leaky bucket is a related design that smooths output to a constant rate instead of allowing bursts.
Worked example
- Inputs: refill 10 requests/s, bucket 100, 1000 requests to send.
- Burst: the first 100 requests go out at once.
- Remaining: 1000 − 100 = 900 requests at 10 per second.
- Minimum time: 900 ÷ 10 = 90 s.
- Daily capacity at the steady rate: 10 × 86,400 = 864,000 requests.
| Refill rate (requests/s) | Minimum time (s) |
|---|---|
| 2.5 | 360 |
| 5 | 180 |
| 7.5 | 120 |
| 10 | 90 |
| 12.5 | 72 |
| 15 | 60 |
| 20 | 45 |
How to read the result
The minimum time is a floor; network latency and server response time add to it, and you will usually send slightly slower than the limit to avoid errors. If the job must finish faster, the options are a higher quota, fewer requests (batch endpoints, caching, conditional requests) or spreading work across allowed keys where the provider's terms permit it.
Common mistakes
- Assuming the burst refills instantly; after the burst, you are limited to the refill rate.
- Ignoring other limits such as per-minute, per-day or concurrent-request caps.
- Retrying immediately after a 429 instead of waiting, which wastes tokens and can extend blocks.
Frequently asked questions
What should a client do after HTTP 429?
Wait as long as the Retry-After header says if present, otherwise back off exponentially with some random jitter.
Is a token bucket the same as a fixed window?
No. A fixed window resets a counter each period, which can allow double bursts at window edges; a token bucket refills continuously.
Does the burst count toward the daily total?
Yes, but once; the steady-state daily figure assumes the bucket is not idle long enough to refill.
Sources: IETF RFC 6585, Additional HTTP Status Codes (429 Too Many Requests) · IETF RFC 9110, HTTP Semantics (Retry-After) · A. S. Tanenbaum and D. J. Wetherall, Computer Networks, Pearson (traffic shaping: leaky and token bucket)