TL;DR: A rate limiter has two jobs: protect everyone else from one noisy client, and tell that client exactly how to behave. Most implementations only do the first. Below: why a token bucket beats fixed windows, an atomic Redis Lua script, Django middleware that keys by identity and charges expensive endpoints more, the headers clients actually need, a client that respects them, and a test that proves the limit holds.
Here's my slightly grumpy opinion: a 429 without Retry-After is a bug. It doesn't stop a misbehaving client. It teaches it to retry harder, at random, until something else falls over.
Most APIs get rate limiting the hard way. A partner's integration goes into a retry loop, a scraper finds the search endpoint, or one customer's nightly sync starts at the same minute as everyone else's. The database is the first thing to notice, and by then every other customer is noticing too.
Rate limiting is easy to bolt on and easy to get subtly wrong.…