Rate limiting
A thousand saves a second
Priya's dashboard shows one player's app sending 1,000 save requests a second, from a bug. Without a limit, everyone's saves slow down.
Rate limiting caps how many requests one client can make in a period of time.
429 Too Many Requests
RFC 6585, from 2012, defines status code 429: "the user has sent too many requests in a given amount of time". The answer "MAY include a Retry-After header indicating how long to wait".
Real numbers: GitHub's API allows 60 requests an hour without signing in, and 5,000 an hour for a signed-in user.
Quick check
Remy's app gets 429 with Retry-After: 30. What should it do?
- Wait 30 seconds before trying again
- Retry immediately, many times
- Delete the player's save
Show the answer
Wait 30 seconds before trying again
Retry-After is the server telling the app exactly how long to wait. Retrying sooner only earns more 429s.
The token bucket
Stripe's engineering blog (2017) describes the token bucket: each request takes a token from a bucket, and tokens drip back in slowly.
A full bucket allows a short burst. Once it is empty, the refill rate is the limit.
Stripe's four limiters
- Request rateHow many requests each user may make per second.
- Concurrent requestsHow many each user may have in progress at once.
- Fleet usageKeeps part of the servers free for the most important requests.
- Worker utilisationDrops lower-priority work when workers are overloaded.
Quick check
A token bucket never allows a burst of requests.
- True
- False
Show the answer
False
A full bucket lets several requests through at once. The limit only bites once the tokens run out.
Read the numbers
1Bucket size: 10 tokens2Refill: 2 tokens per second3The bucket is full.
A client sends 14 requests at once. How many get through right away?
- 10, the full bucket; the other 4 get 429
- All 14
- 2
Show the answer
10, the full bucket; the other 4 get 429
Each request takes a token. Ten tokens let ten through; the rest wait for the refill, 2 a second.
Feel the pace
A bucket's size and its refill rate together decide what a client can do. The next lesson puts you on the sending side.
Bolt says: Next: pace your saves through a token bucket.
Fact-checked 12 October 2026
- RFC 6585: Additional HTTP status codes rfc-editor.org
- GitHub: Rate limits for the REST API docs.github.com
- Stripe: Scaling your API with rate limiters stripe.com