Lesson 17 / 24

Rate Limiting

Q: A client exceeds its rate limit. What should the API return?

429 Too Many Requests. 429 specifically signals rate limiting, ideally with a Retry-After header telling the client when to try again.

Protecting an API from abuse and runaway clients.

Why limit requests

Without a cap, one misbehaving script, a retry storm, or a malicious actor can overwhelm your API and degrade it for everyone else. Rate limiting caps how many requests a key/user/IP can make in a window.

Telling the client

Return 429 Too Many Requests with headers so well-behaved clients can back off automatically.

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1725448800
Retry-After: 30

A leaking bucket

The token bucket algorithm fills a bucket with tokens at a steady rate; each request spends one. Short bursts drain saved-up tokens, but you can never sustain more than the fill rate — smooth, and simple to reason about.

Quick check: A client exceeds its rate limit. What should the API return?

403 Forbidden
429 Too Many Requests
503 Service Unavailable

Answer

429 Too Many Requests — 429 specifically signals rate limiting, ideally with a Retry-After header telling the client when to try again.