What Should an API Reference Say About Rate Limits?
From the earlier reference collection. Read the current software blog.
Rate-limit documentation should state the limit’s scope and window, describe what a client observes when it is exceeded, and give bounded retry guidance.
Define the limit precisely
Say what is counted, over what interval, and which identity the limit applies to. A limit may count requests per account, token, IP address, endpoint, or some combination. “Requests are limited” leaves clients unable to plan. If different endpoints have different policies, document them separately and identify whether the limit is fixed, rolling, or otherwise calculated.
Provide the number and time window only if they are established policy. Do not invent a generous-looking limit or imply that all users receive the same quota when limits vary by account or may change. If the value is configurable or subject to change, say where a client can discover its current allowance, if such a mechanism exists.
Describe the observable response
Explain what the server returns when a request exceeds the limit: status code, response body shape, and any documented headers that indicate remaining quota or reset time. If behavior varies, label the conditions. A client developer needs to distinguish a throttling response from authentication failure, malformed input, or a temporary server error. Include a representative response only when it reflects actual behavior, and mark placeholder values clearly.
State whether rejected requests count toward the limit and whether limits are shared across concurrent clients using the same account. These details influence retry loops and batch jobs. If the server does not provide a reset time, say that rather than fabricating a header. Include links to relevant error definitions so the rate-limit section does not become disconnected from the rest of the API reference.
Give restrained retry guidance
Tell clients how to recover without creating more load. If the response supplies a retry delay, instruct clients to honor it. Otherwise, recommend bounded exponential backoff with jitter, a maximum attempt count, and a stop condition that surfaces the failure to a person or calling system. A client should not retry indefinitely or immediately repeat the same request in a tight loop.
Use a practical scenario: a batch importer receives a throttling response for one page of results. It should pause according to the documented signal, retry that page, and preserve already completed pages so it does not restart the whole job. Explain whether requests are safe to repeat, especially for operations that change server state. Rate-limit documentation is useful when it lets a client stay within policy and recover predictably; it should not promise that retries will eventually succeed.