Refill stream, burst drawdown, and recovery runwayLive current inputs
Computer & IT
API Rate Limit Capacity Calculator
Design a weighted token-bucket API limit from client demand, endpoint cost, retry overhead, burst depth, refill capacity, and recovery time.
Base requests —
Weighted steady demand —
Safe refill capacity —
Steady headroom —
Peak weighted demand —
Tokens drawn during burst —
Maximum supported burst —
Bucket outcome —
Token-bucket timeline
Token-bucket timeline
Refill stream, burst drawdown, and recovery runway
The bucket level falls only when weighted demand exceeds safe refill. The recovery line shows how unused refill restores permission after the burst.
Current scenario Capacity or comparison
Result composition and constraint comparisonUpdates with every input
Planning checkpoints
Plan the rate-limit rollout checkpoints
Translate the token budget into an enforceable, observable, and client-safe API contract.
Current modelLive
Review steps6
01Checkpoint
Name the backend resource being protected.
02Checkpoint
Benchmark and version endpoint token weights.
03Checkpoint
Set tenant and global refill policies.
04Checkpoint
Test the declared burst and repeated bursts.
05Checkpoint
Verify Retry-After, jitter, and idempotency behavior.
06Checkpoint
Alert on bucket exhaustion and enforcement overshoot.
How to use the weighted token-bucket design
- Identify whether the limit protects CPU, database writes, search, vendor calls, queue production, risk, or a commercial allowance. Raw request count is weak when endpoint costs differ.
Weighted token-bucket design fundamentals
Assign evidence-based weights
Choose a cheap base operation, then express expensive routes relative to measured backend use. Keep weights simple, versioned, and observable.
Review weights after query, cache, data-size, or feature changes.
Calculation method
Weight endpoint cost before sizing steady refill and burst depth
Raw requests are converted to weighted tokens because endpoint cost differs. Retry overhead increases sustained demand, while stored bucket tokens cover only temporary demand above safe refill.
Detailed calculation process and general formulas
R = C x N / 60w_avg = (1 - s) x w_read + s x w_writeT_steady = R x w_avg x (1 + e)T_safe = G x f x uT_peak = b x T_steadyDraw = max(T_peak - T_safe, 0) x tt_max = B / max(T_peak - T_safe, 0)t_recover = min(B, Draw) / max(T_safe - T_steady, 0) Every formula above uses the current calculator's own quantities. The live worked example later on this page substitutes the entered values and reconciles the result.
Reading the analysis
Model clients and retries
Active clients means credentials capable of producing the entered rate during the same interval, not every registered account.
Include observed retry amplification, but fix missing jitter, attempt caps, idempotency, and Retry-After handling instead of normalizing bad behavior.
Improving the plan
Set refill and depth separately
Refill protects sustainable long-run capacity. Bucket depth admits a bounded legitimate burst and must not conceal a sustained deficit.
Evaluate repeated bursts and recovery time; a bucket that never recovers will throttle later legitimate work.
Decision scale
Distributed enforcement
Central counters, local leases, sharding, and eventual reconciliation can overshoot. Quantify per-node overshoot and failure behavior.
Combine global protection with tenant, endpoint, credential, and concurrency policies when fairness or operation duration matters.
More marginMore resilience to variation Less marginMore sensitive to assumptions
The live result above supplies the current decision point.
Scenario comparison
Burst-policy comparison
This comparison holds the other current inputs constant so the selected policy or demand assumption remains the variable under review.
| Burst multiplier | Peak tokens/s | Bucket draw | Supported seconds | Recovery time | Outcome |
|---|
Worked example
Your complete weighted token-bucket design calculation, step by step
This example follows the values currently entered above and updates whenever an input changes.
Scope and limitations
Model limitations
This deterministic shared-bucket model excludes counter lag, strict tenant fairness, sliding windows, adaptive limits, adversarial traffic, queueing latency, regional partitions, circuit breakers, and downstream quota resets.
Key terminology
Weighted token-bucket design glossary
- C
- simultaneously active clients; measured in clients.
- N
- request rate per client; measured in requests/client/min.
- s
- write-request share; measured in decimal.
- w
- endpoint token weight; measured in tokens/request.
- e
- retry overhead; measured in decimal.
- G
- gateway instances; measured in gateways.
- f
- refill per gateway; measured in tokens/s.
- B
- bucket depth; measured in tokens.
Important note
A larger bucket permits a longer burst but does not repair a sustained refill deficit. Gateway count may increase enforcement capacity without increasing the protected backend's safe throughput.
Frequently asked questions
Why weight writes more heavily?
Writes often consume validation, locks, replication, or downstream calls not represented by request count.
What does refill utilization protect?
It preserves room for skew, failover, enforcement overshoot, and measurement error.
Should retries consume tokens?
Usually yes because they create work. Define refunds cautiously and use idempotency for writes.
Token bucket or sliding window?
Token buckets allow bounded bursts; sliding windows enforce a rolling count. Choose the contract the service needs.
Can more gateways raise the safe limit?
Only if the protected backend capacity also scales. Gateways cannot multiply one shared database or vendor quota.