Pace the requests

Play this lesson

Four saves, one bucket

Shard Garden's save server gives each player a token bucket of 3 tokens, and 1 new token drips in every second. Each save uses a token. A save with no token gets 429 Too Many Requests.

The app has 4 saves to send.

Try it

Send four saves

Send a save, or wait a second for a token. Get all four saves through.

Try it in the lesson

Quick check

Why did the fourth save have to wait?

  1. The first three used all 3 tokens, and a new one arrives only once a second
  2. The server was down
  3. A player may only save once a minute
Show the answer

The first three used all 3 tokens, and a new one arrives only once a second

The bucket allows a burst of 3. After that, the refill rate, one a second, is the limit.

Burst and steady rate

The bucket's size sets the burst: how many requests may come at once. The refill sets the long-run rate.

Remy tunes both: big enough for a normal moment, like the end of a wave that saves several things, small enough that a broken app cannot flood the server.

Quick check

Retrying instantly after a 429 is the fastest way to get the save through.

Show the answer

False

The token is not back yet, so an instant retry is refused again. Waiting for Retry-After is both faster and kinder to the server.

Clients that listen

A good app reads Retry-After, waits that long, adds a little jitter, and tries again. A bad one hammers the server and keeps getting refused.

Tune it

The end of a wave sends 5 saves at once. The bucket holds 3. What should Remy change?

  1. Raise the bucket size to at least 5, and keep the refill rate
  2. Lower the refill rate to 1 a minute
  3. Remove the limit completely
Show the answer

Raise the bucket size to at least 5, and keep the refill rate

A normal burst should fit in the bucket. The refill rate still stops a broken app from flooding the server.

On the studio board

The studio adds a decision to the board:

Every public API has a limit and answers 429 with Retry-After. The app waits that long.

Shard Garden now has an architecture that can grow: modules first, contracts, queues and events, caches at every level, indexes, transactions, replicas, a plan for shards, safe migrations, and retries that cannot charge twice.

Bolt says: Boss time: one quiz across the whole Architecture stage.

Fact-checked 12 October 2026