A token bucket: refusing on the server, spacing on the client
The clock is a number of milliseconds you pass in. Tokens are stored times 1000 so every step is a whole number.
Providers cap how many requests and tokens you may send per minute and answer with HTTP 429 when you go over. Headers tell you how much quota is left and when it resets, and a token bucket lets you stay under the limit before the server has to refuse you.
Change the code and press Run (Ctrl+Enter). Predict what will happen first, then break it on purpose and read what changes. Your edits are saved and match the lesson page.
Ready for more? This phase has 6 hands-on exercises with automatic checks.
Practice questions
Write the code in the editor, run it, then open the model answer to compare.
Using the TokenBucket idea, write a function simulate(capacity, per_sec, times) that returns a list of "ok" or "wait N" strings for requests at those millisecond times, using tokens times 1000. Test it with capacity 1, 1 per second and times [0, 0, 1000].
Write parse_seconds(text) that turns strings like "2.5s" into whole milliseconds (just seconds, no minutes). Print it for "2.5s" and "0.25s".
Explain it without notes
What is a rate limit and what does the server answer when you pass it?
How does a token bucket allow bursts yet keep a long-run rate?
What should a client do when it gets a 429 with a retry-after header?
Why can a limit on tokens per minute be hit with few requests?
Expected output
server side (4 tokens, 2 more every second):
t=0: allowed
t=0: allowed
t=0: allowed
t=0: allowed
t=0: denied (429), retry in 500 ms
t=0: denied (429), retry in 500 ms
t=500: allowed
t=600: denied (429), retry in 400 ms
t=1100: allowed
t=5000: allowed
t=5000: allowed
t=5000: allowed
t=5000: allowed
t=5000: denied (429), retry in 500 ms
client side (8 requests wanted at t=0):
start times: 0, 0, 500, 1000, 1500, 2000, 2500, 3000