Rate limits usually start as a defensive number picked during an incident. They end as the thing that determines whether a customer's integration is pleasant or infuriating, which makes them a product surface whether or not anyone treats them as one.
The three failures
- The limit is undocumented, so integrators discover it in production.
- The limit is uniform, so the endpoint that costs you nothing is throttled like the one that runs a report.
- The 429 carries no retry guidance, so every client implements a different, worse backoff.
What a good limit tells you
A well-designed 429 answers three questions in its headers: what the limit was, how much you have left, and when to come back. Every serious SDK already reads those headers. Sending them correctly costs nothing and removes an entire class of support ticket.
Tier by cost, not by convention
A read that hits a cache and a report that scans a quarter of ledger history should not share a budget. Group endpoints by what they actually cost you to serve, publish the groups, and let integrators plan against them.
If your integrators cannot predict when they will be throttled, your rate limit is not a limit. It is a surprise.
Watch the ones who are close
The useful alert is not the consumer who hit the limit. It is the consumer who has been sitting at 92% for a week, because that integration is about to grow into an incident and a support thread you can pre-empt with an email.