API Rate Limiting: Token Bucket Defense

Traffic

Request rate 10 req/s

Refill rate (tokens/s) 8 tok/s

Bucket capacity 25 tok

Bucket state

25.0 / 25 tokens

Accepted

Rejected (429)

Rejection rate

0.0%

Throughput

0.0 req/s

How it works

The token bucket is the algorithm behind almost every real API rate limiter (Stripe, GitHub, Cloudflare, AWS API Gateway). A bucket holds up to C tokens and refills continuously at rate r:

tokens(t) = min(C, tokens(t-Δt) + r·Δt)

on each request:
  if tokens ≥ 1:  tokens -= 1;  ACCEPT (200)
  else:            ACCEPT-nothing; REJECT (429 Too Many Requests)

This gives two guarantees at once: the long-run average a client can sustain is capped at exactly r requests/second (the refill rate), while a short burst up to C requests is still allowed instantly, because tokens can accumulate in the bucket while the client is idle. That is why capacity C is often called the "burst allowance" and refill rate r the "sustained rate".

Request rate — how fast the client (or attacker) fires requests at the API.
Refill rate — tokens the server credits back per second; this is the enforced sustained limit.
Bucket capacity — the maximum burst the bucket can absorb before it starts rejecting.
Fire burst attack — queues a sudden spike of 40 requests, the classic way an attacker (or a buggy retry loop) tries to overwhelm an endpoint; watch the bucket drain and 429s start firing once it empties.

Real-world relevance: without a rate limiter, brute-force login attempts, credential-stuffing bots and scraping scripts can hit a web app at unlimited speed. The token bucket is the primary defense — it is cheap to compute (one subtraction per request), fair to legitimate bursty traffic, and it is exactly what sits in front of most production login and API endpoints today.

Accepted request Rejected (429) Token

tokens: 25.0 / 25

⚠ Couldn't load the 3D engineThree.js failed to load from the CDN. Check your connection and reload.