Token bucket (rate limiting)

In short: With the token bucket method, a bucket fills with tokens at a fixed rate. Each request uses a token; if the bucket is empty, the request is rejected or delayed.

In more detail: The bucket has a maximum size (burst) and a refill rate. Short spikes are allowed as long as enough tokens were saved beforehand, but in the long run only the refill rate applies.

In Depth

• Parameters: Capacity (for example 20) and rate (for example 5 per second).
• Comparison: Fixed-window counters are simple but allow double spikes at the window boundary. Sliding window is more exact; token bucket smooths load elegantly.
• Response: HTTP status 429 “Too Many Requests”, often with a Retry-After header.
• Distributed: The counter lives in shared storage (for example Redis) so all servers see the same limit.
• Key: Count separately per IP, user or API key.

See also: Rate limiting