HuntsvilleEngineers mark
Subscribe

Token Bucket Rate Limiter

Size a token bucket for an API or network path — sustained rate, burst allowance, and how long a burst can run before it throttles.

Inputtokens(t) = min(C, tokens₀ + r·t − Σcost) , burst = tokens₀ / (arrival·cost − r) , sustained = r / cost

Your recent runs (stored only in your browser)

No calculations yet — results land here so you can compare runs.

The engineering

A token bucket fills at a committed rate r up to a capacity C. Each request spends cost tokens; if the bucket is dry the request is throttled. Capacity sets how big a burst you tolerate, r sets the long-run ceiling. This card tells you the sustainable request rate, and — when arrivals outrun the fill — how many seconds a full bucket buys you before the limiter kicks in.

Rule of thumb: capacity ÷ rate is your maximum burst window in seconds when starting full. Size C for the largest legitimate spike (a batch job, a retry storm) but no larger, or you defeat the point — an oversized bucket lets an attacker dump the whole burst at once. If your effective accept rate equals r/cost, you're rate-limited by fill, not by burst.

Where this math comes from

The token bucket grew out of 1980s packet-network traffic policing, where carriers needed to admit bursty traffic without letting any one source swamp a link. The idea is deliberately simple: mint permission tokens at a fixed clock rate, let them pile up to a cap, and charge each packet a token — so idle senders bank credit for a later burst, while a firehose gets clipped to the mint rate.

Juha Heinanen and Roch Guerin pinned the mechanism to paper for the IETF in RFC 2697 (September 1999), the Single Rate Three Color Marker, defining committed information rate (CIR) and committed burst size (CBS) — exactly the fill rate and capacity on this card. The same math now backs virtually every cloud API gateway and rate-limit middleware in production.

  1. 1986Jonathan TurnerDescribes the leaky/token bucket for ATM traffic policing in network literature.
  2. 1994ATM ForumAdopts the Generic Cell Rate Algorithm — a token-bucket policer — for traffic conformance.
  3. 1999J. Heinanen & R. GuerinRFC 2697 formalizes the single-rate three-color marker with CIR and CBS.
  4. 2000IETFRFC 2698 adds the two-rate marker (CIR + PIR) for peak-rate shaping.

See the full timeline of the math behind every calculator →

Runs entirely in your browser — nothing you enter leaves this page. Your recent runs are stored only on your device.