A token bucket is a container holding a fixed number of tokens, and each request uses up one token. The bucket is refilled at a steady rate up to its capacity, so a client that sends requests more slowly than the refill rate never runs out of tokens.

When the bucket is empty, the server rejects further requests with 429 Too Many Requests. The server also tells the client, in a Retry-After header, how long to wait until tokens are refilled.

The client waits for the Retry-After time before sending again, avoiding a retry sent at an arbitrary interval that gets rejected a second time.