The refusal shapes what happens next
How you refuse a request shapes what the client does next, and a badly communicated limit creates the exact retry storms your limiter exists to prevent.
Return the status code that means too many requests, not a generic error, because clients and SDKs key their retry behaviour off that code.
Include a header saying how many seconds to wait, which converts a guessing client into an obedient one.
Send the limit, the remaining count, and the reset time on every response, not only on refusals. The remaining count on successful responses is the load-bearing one, because it lets a well-built client slow down before it hits the wall.
Ask your clients for backoff with randomness in return. Wait a second, then two, then four, then eight, with jitter added so a thousand rejected clients do not all come back on the same tick.
Implement that in your own SDKs so your customers get correct behaviour without reading a specification. The jitter is the difference between a smooth recovery and synchronised waves of retries.
Two refinements
Add two product-level refinements that separate good APIs from adequate ones. Charge more for expensive operations, so a search costs ten tokens where a simple fetch costs one, being honest about what you are actually protecting.
And give large customers warning. Alert them at 80 percent of their quota, by dashboard or webhook, so the conversation about upgrading happens before their integration breaks on launch day rather than after.
Worked example
Chandra's team at a payments API notices a pattern in support tickets: customers hitting limits see failures with no explanation, retry immediately, and make their own problem worse; one customer's checkout integration loops hard enough to stay rate limited for 40 minutes. The fix ships in one sprint: 429s gain Retry-After, all responses gain the RateLimit trio, and the official SDKs get exponential backoff with jitter that honors Retry-After automatically. The public docs add a page showing the headers with worked examples. Over the next quarter, rate-limit support tickets drop from about 30 a month to 4, and the average duration a throttled key stays throttled falls from minutes to seconds, because clients now back off instead of hammering. Nothing about the limits changed, only the communication.