How does a per-user token bucket beat a fixed-window counter?

Category: System Design

Answer

Token bucket smoothly absorbs bursts: bucket of N tokens refilling at R per second; each request consumes 1; reject if empty. Fixed-window counter resets every minute, allowing 2x the rate at the window boundary. Token bucket is the standard for protecting downstream quotas.

Concrete examples from the fca project context

Example 1

Redis Lua script for atomic refill+consume across replicas.

Example 2

Per-user bucket key: rl:user:{user_id}; refill 60 tokens / minute.

Example 3

Middleware returns 429 + Retry-After.

Data flow / flow chart

request -> bucket.consume()
  if allowed: proceed
  if empty:  429 + Retry-After

Takeaway

Token bucket for burst tolerance. Sliding window for fairness. Leaky bucket for stable rate.