Token bucket rate limit calculator

A token-bucket rate limiter is the standard model behind API throttling, gateway quotas, and client-side back-pressure. It refills the bucket with a hard clamp at capacity, decides allow or deny, reports tokens remaining after the decision, and when the burst is denied it computes how long you must wait for enough tokens—or tells you the request can never be satisfied because it exceeds capacity or refill is zero. The same pure deterministic module powers the free browser tool and the API path, so design reviews, load-test scripts, and production simulators never disagree on edge cases such as a full bucket, a partial refill, or a request larger than the burst ceiling.

How the token bucket algorithm decides allow or deny

The token bucket stores a non-negative token balance that never exceeds capacity. Elapsed time is caller-supplied so the math stays deterministic—no wall clock is read—so the same inputs always produce the same allow decision, remaining balance, and wait seconds across runtimes and goldens. Between checks, tokens accumulate at refill_rate tokens per second for the elapsed duration, then the balance is clamped with min(capacity, tokens + elapsed times refill_rate). That clamped value is tokens_available—the amount you can spend right now. A burst that costs request_count tokens is allowed when tokens_available is at least request_count; on allow, tokens_remaining becomes tokens_available minus request_count and tokens_consumed equals request_count. On deny, no tokens are spent: tokens_remaining stays at tokens_available, tokens_consumed is zero, and deficit equals request_count minus tokens_available. Wait time is deficit divided by refill_rate when refill is positive and the request is not larger than capacity; otherwise the request cannot be satisfied later either (can_satisfy is false), which covers both a cost above the burst ceiling and a frozen bucket with zero refill. Capacity is the burst allowance: a full bucket of ten with a slow refill still lets a single ten-token spike through, which is why gateways choose capacity for peak bursts and refill_rate for sustained average traffic.

Input contract, response fields, and validation errors

POST a JSON body with five required finite numbers. capacity must be greater than zero and is the maximum tokens the bucket can hold after refill. refill_rate must be greater than or equal to zero and is measured in tokens per second; zero means the bucket never recovers once empty. tokens is the balance before applying this elapsed interval and must be non-negative; values above capacity are accepted and are clamped when computing tokens_available after refill. elapsed is seconds since the last update and must be non-negative. request_count is how many tokens this burst needs and must be greater than zero. Missing fields, non-numeric strings, NaN, Infinity, and out-of-range signs fail with invalid_input naming the field and are not billed. On success the body echoes the five inputs, then returns tokens_available after refill, allowed as a boolean, tokens_remaining after the spend decision, tokens_consumed, deficit, wait_seconds (zero when allowed or when the request can never pass), can_satisfy, and a short formula string restating the update rule. Example: capacity ten, refill_rate two per second, tokens five, elapsed one and a half seconds, request_count three yields tokens_available eight (five plus three from refill, still under capacity), allowed true, tokens_remaining five, and wait_seconds zero. A second call that asks for nine tokens with the same available eight is denied with deficit one and wait_seconds of one half second at two tokens per second.

Where a token-bucket calculator earns its keep

Edge and gateway authors use the calculator as an oracle while implementing Redis or in-memory buckets, comparing their local state machine to this closed-form result for identical inputs. Educators and SRE interviews use it to demonstrate that token bucket is not the same as a pure leaky bucket: bursts are allowed up to capacity, then smooth refill restores headroom. Failed validation does not consume balance. API product teams size capacity and refill before shipping a quota: they plug candidate numbers and sample burst sizes to see whether legitimate spikes pass while abusive floods wait. Load-test harnesses and chaos scripts call the same pure endpoint to assert that a synthetic client that follows wait_seconds never over-spends relative to the documented limit. Keep requests small, pin the rounded numeric fields in tests, and you get reproducible allow and wait answers for design docs, SDK examples, and production dry-runs without standing up a full rate-limit service.