API 429 Errors: Rate Limits, Retry-After, and Safe Retries

An API 429 error is triggered when the server rejects a request due to a rate or usage limit being exceeded. Before retrying, carefully examine the response body and headers, identify the specific limit, and ensure that only a bounded retry is made. For operations with side effects, confirm if the initial request was successful before sending another.

The RFC 6585 standard defines a 429 status code as "Too Many Requests," but the standard does not specify a uniform method for determining when to wait. The server may limit a single resource, a key, a project, an organization, or even the entire cluster, so a status 429 alone does not provide a definitive answer on how long to wait.

Different APIs utilize 429 errors for various reasons, such as temporary rate limit exceeding, exhausted credits, project or organization limits, and more. Each reason will have a different code and may require distinct handling strategies. It is crucial to consult the relevant API's documentation to understand the specific cause of the 429 error and the appropriate recovery actions.

When encountering a 429 error, first save the complete HTTP status, error body, and headers (excluding the API key) for later reference. If a valid "Retry-After" header is present, consider it the minimum delay and add a small random jitter to prevent multiple workers from starting their retries simultaneously. If no "Retry-After" header is present or is invalid, use an exponential backoff strategy with jitter and a maximum number of attempts along with a total time limit.

Different providers may have varying Retry-After formats, so always verify the current contract of the specific API being used to ensure correct interpretation of the header. If the Retry-After header is not found or not usable, employ a carefully designed retry mechanism that incorporates backoff and jitter to minimize the impact on the system while allowing sufficient time for the rate limit to reset.