What is Token Bucket
Token Bucket — a rate-limiting algorithm where a "bucket" is filled with tokens at a constant rate (r tokens/sec). Each request consumes 1 token. If the bucket is empty → reject. If full → no new tokens added. Allows bursts (up to bucket capacity) on top of the average rate. Alternatives: leaky bucket (no burst), sliding window (precise but expensive), fixed window (edge effects).
Below: details, example, related terms, FAQ.
Details
- Capacity: max tokens in bucket (burst size)
- Refill rate: r tokens/sec (long-term average)
- Per-key: one bucket per user/IP/API key
- Storage: Redis atomic ops (INCR/DECR + EXPIRE)
- Typical: 60 req/min = 1 token/sec refill + capacity 10 (burst)
Example
# Redis Lua pseudocode
local tokens = redis.call("GET", key) or capacity
tokens = min(capacity, tokens + (now - last_refill) * rate)
if tokens >= 1 then
redis.call("SET", key, tokens - 1)
return allow
else
return deny
endRelated Terms
Learn more
Frequently Asked Questions
Token bucket vs sliding window?
Token bucket: simple O(1), allows bursts. Sliding window: precise count over any time window, but O(log n) or Redis sorted-set overhead.
How to choose parameters?
Average rate (r) = your target RPS. Capacity = typical burst (10-30 sec worth). E.g. 10 req/sec average + 300 capacity = 30 sec burst.
Rate limit per-IP or per-user?
Both. per-IP defends anonymous abuse. per-user defends credential stuffing after login.