429 Too Many Requests: what it means and how to handle it

An API returns 429 Too Many Requests when your app sent more requests than the API allows in a period of time. The request itself is fine. You sent it too often, so the API turned it down. If you wait and send it again, it usually succeeds. The response often includes a Retry-After header that tells you how long to wait. For more information, see RFC 6585, section 4.

What a 429 looks like in popular APIs

Every API implements rate limits differently. The status code, the headers, and the error body all vary, so code that handles one API correctly can mishandle the next.

How to handle a 429

1. Decide whether to retry at all. If the error says that your quota, credits, or spend limit is used up, retrying won't help. Tell the user, and alert yourself.
2. Wait as long as the API asks. If the response has Retry-After, wait that long. It's either a number of seconds or an HTTP date. If the API uses rate limit headers instead, like GitHub's x-ratelimit-reset, wait until the reset time.
3. Otherwise, back off. Without a hint from the API, retry with exponential backoff and random jitter, and stop after a few attempts.
4. Tell the user what's happening. "Busy, retrying in 5 seconds" beats a spinner that never ends.
5. Slow down before the next 429. If the API sends rate limit headers, use the remaining count to pace your requests.

async function fetchWithRetry(url, options, attempts = 3) {
  for (let attempt = 1; ; attempt++) {
    const response = await fetch(url, options);
    if (response.status !== 429 || attempt === attempts) {
      return response;
    }
    const retryAfter = response.headers.get('retry-after');
    const waitMs = retryAfter
      ? (isNaN(retryAfter) ? new Date(retryAfter) - Date.now() : retryAfter * 1000)
      : 2 ** attempt * 1000 + Math.random() * 1000;
    await new Promise(resolve => setTimeout(resolve, Math.max(waitMs, 0)));
  }
}

Many SDKs retry 429s for you. For example, the OpenAI Python SDK retries 2 times by default, and the .NET standard resilience handler retries 3 times and honors Retry-After. When the SDK runs out of retries, your code gets the error, so it still needs a plan.

How to test that your app handles 429

You rarely see a 429 while you develop. The API is fast, you're the only user, and your test data is small. So the way you test 429 handling decides whether you find the bugs before your users do.

Try it on your app

Dev Proxy intercepts your app's requests to the APIs you choose and returns 429s, with the API's own headers and error format, while your app keeps calling the real URLs. It also tells you when your app retries before the Retry-After time is up.

Download the preset for the API your app calls, and start Dev Proxy with it:

devproxy config get github-rate-limiting
devproxy --config-file "~dataFolder/configs/github-rate-limiting/.devproxy/devproxyrc.json"

Then run your app as usual and watch what it does. To install Dev Proxy, see Set up Dev Proxy.

Next steps

See also

• What is rate limiting?
• What is throttling?
• Test how your app handles GitHub API rate limits
• Test how your app handles OpenAI rate limits
• Test retries and timeouts in .NET apps