Calculate appropriate API rate limit thresholds based on capacity and client demand.
The token bucket algorithm allows short bursts up to the bucket's full capacity, while limiting the long-run sustained rate to the refill rate: allowed_rps = bucket_size ÷ refill_interval ÷ request_cost. A larger bucket size permits bigger bursts without changing the sustained rate, while a shorter refill interval increases the sustained rate a client can maintain indefinitely — the two parameters are independent knobs for burst tolerance versus steady-state throughput.
allowed_requests = rate_limit × window_seconds
Bucket size controls how large a burst is tolerated (how many requests can fire instantly after the bucket is full); refill rate (bucket_size ÷ refill_interval) controls the long-run sustained rate — they can be tuned independently to allow bursty traffic patterns while still bounding average load.
Fixed window counters reset abruptly at interval boundaries, which allows a client to send 2x the intended rate right at a window edge; token bucket (and its close relative, leaky bucket) smooths this out by continuously refilling, avoiding the edge-of-window burst problem.
Weight expensive operations (e.g. bulk exports, complex search queries) with a higher token cost than simple reads, so the same bucket capacity naturally throttles resource-intensive requests more aggressively without needing a separate limiter per endpoint.
Size the bucket to comfortably accommodate legitimate burst patterns (e.g. a page load firing several parallel API calls) while still being small enough that a misbehaving or malicious client can't cause a meaningful spike — profile real traffic patterns rather than guessing.