API rate limiting and HTTP 429

What it means

A token bucket represents a limited request budget. Here, a token is a unit of that budget, not a login credential. Bucket capacity is the maximum balance; request cost is the amount a modeled request needs.

Admission means only that the request fits this rate budget. The token balance is a teaching input, not a measurement of a real API quota. A provider decides which callers and requests its limit covers and how it counts them.

Try it

Simulation: change Tokens before refill from 2 to 3, then select Compare with baseline. Inspect which result changes and why. This is a local calculation: no API request is sent and no real quota is checked.

The baseline result is Rate-limited: would return 429. With zero elapsed seconds, refill adds nothing: only 2 tokens are available for a request costing 3. The model refuses it without spending those 2 tokens. After your change, compare the available balance with the same request cost.

Keep Bucket capacity at 5, Refill tokens per second at 1, Elapsed seconds at 0, and Request cost at 3. Only the starting token balance changes.

Reset restores Bucket capacity to 5, Tokens before refill to 2, Refill tokens per second to 1, Elapsed seconds to 0, and Request cost to 3. It clears input errors and the baseline comparison. There is no running clock or stored event history to reset. Your independently opened FAQ answers and About this model disclosure stay as you left them.

How it works

The calculation has three stages:

1. Add refill: starting tokens + refill rate × elapsed seconds.
2. Apply the capacity cap: available tokens = min(capacity, refilled amount).
3. Compare request cost with available tokens. If the cost fits, subtract it. If it does not fit, refuse the request and leave the available balance unchanged.

Equality is enough for admission: a request costing exactly the available balance is allowed and leaves zero tokens. In this teaching policy, a refusal maps to “would return 429.” HTTP itself does not require this algorithm.

Capacity and refill rate answer different questions. Capacity bounds the budget that can be available at once; refill rate determines how quickly a depleted budget can recover. For a separate synthetic cap check, start with 4 tokens, capacity 5, refill rate 10 tokens per second, elapsed time 1 second, and cost 5. Refill gives min(5, 4 + 10 × 1) = 5 tokens—not 14. The request is allowed and leaves 0 tokens. The cap discards the excess refill rather than storing it for a later burst.

This also explains why waiting is not a universal remedy. If request cost exceeds capacity, no entered interval can make that request fit this model. If refill rate is zero and the balance is insufficient, more elapsed time adds nothing. Even when waiting would make the arithmetic fit, the calculation says nothing about whether repeating the real operation is safe.

Worked example

This is the synthetic baseline, not a captured production response.

Refill gives min(5, 2 + 1 × 0) = 2 tokens. Request cost 3 exceeds that amount, so the result is Rate-limited: would return 429, with 2 tokens remaining in this single step. The bucket’s capacity of 5 does not mean 5 tokens are currently available.

This fixture maps refusal to HTTP 429. A real 429 may include Retry-After, but HTTP does not require either that header or this bucket algorithm.

What changes when the condition changes

Change only Tokens before refill from 2 to 3. Keep capacity 5, refill rate 1 token per second, elapsed time 0 seconds, and request cost 3.

The result becomes Allowed by token budget: min(5, 3 + 1 × 0) = 3 tokens. The cost exactly fits, so 0 tokens remain after admission. No refill caused this change: elapsed time is still zero. The extra starting token moved the request across the admission threshold. Capacity remains 5 even though the remaining balance is 0.

This result establishes only that the synthetic request fits the entered budget. It is not authorization or proof that a real service will accept the request.

In practice

For an API you are authorized to use, start with read-only evidence: the provider’s documentation for the affected endpoint and caller, and any response details already available to you. Establish the limit’s scope, how requests are counted or costed, whether Retry-After was supplied, and which retry behavior the provider supports. Do not infer those facts from the synthetic bucket.

Keep two questions separate: did this attempt receive a rate-limit response, and is the intended operation safe to repeat? A 429 on one attempt does not resolve the outcome of an earlier timed-out attempt.

Stop automatic replay when an operation’s outcome is unknown and you have not established that repeating its effect is safe. Seek the provider’s documented way to determine the outcome or identify the same operation. Respect applicable retry guidance; do not invent a server-specified delay when Retry-After is absent. Do not create extra identities or parallel retries to evade an imposed limit. No live test request or service change is needed to use this example.

Limits and unknowns

Time is the entered interval, never a wall clock. Changing Elapsed seconds recalculates one step from the entered starting balance; it does not advance a running service. An allowed result does not become the starting balance of a later request automatically. There is no request history, and no request is sent or real quota checked.

The supported ranges are: Bucket capacity 1–100 tokens; Tokens before refill 0–100 tokens, subject to capacity; Refill tokens per second 0–100; Elapsed seconds 0–600; and Request cost 1–100 tokens. Inputs must satisfy the numeric field requirements. A starting balance above capacity is invalid rather than an admission decision. The interface shows Current visible input is invalid, with an explanation that the starting balance exceeds capacity. Invalid input removes the calculated outcome until you correct it or use Reset.

For valid inputs, this local model can calculate a budget decision. It cannot determine a real provider’s remaining quota, authorization decision, shared caller scope, retry delay or operation outcome. Those remain unknown without applicable documentation and observations. Without JavaScript, the initial example remains readable, but the interactive controls are unavailable.

What to carry forward

Treat rate-budget availability and retry safety as separate questions. Waiting may replenish a budget, but it cannot make an oversized request fit this capped model or resolve an unknown operation outcome. Your next step should be to establish the applicable limit and retry contract—not to assume that another attempt will succeed.