429 Too Many Requests: handle rate limits the right way

429 Too Many Requests is a rate limit: you sent more requests in a period than the server allows, so it's telling you to slow down. Nothing is broken. Whether that's a problem depends on which side you're on.

If you're calling someone else's API

Respect Retry-After

Most APIs tell you how long to wait, and how much of your allowance is left:

HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1791212400

Retry-After is either seconds or a date. Waiting exactly that long, then retrying, is the polite and fastest way to recover.

Back off, with jitter

Without a Retry-After, wait longer after each failure (1s, 2s, 4s, 8s…) and add a little randomness so many workers don't all retry at the same moment:

async function withRetry(fn, attempts = 5) {
  for (let i = 0; ; i++) {
    const res = await fn();
    if (res.status !== 429 || i === attempts - 1) return res;
    const after = Number(res.headers.get("retry-after"));
    const wait = after > 0 ? after * 1000 : 2 ** i * 1000 + Math.random() * 500;
    await new Promise((r) => setTimeout(r, wait));
  }
}

Make fewer requests

• Cache responses that don't change often.
• Use batch endpoints instead of one call per item.
• Use webhooks instead of polling for changes.
• Spread scheduled jobs out, instead of every customer's sync starting on the hour.

If your own site returns 429

Rate limits protect you from abuse, but they can catch real users too:

• Shared IP addresses. An office, a university or a mobile carrier can put thousands of people behind one IP. A per-IP limit treats them as one heavy user.
• Your own frontend. A page that fires 40 API calls on load, or retries in a tight loop, can trip your own limits.
• Bot protection. CDN and WAF rules sometimes return 429 to traffic they consider automated, including monitoring and search engine crawlers.

Log which limit fired and for whom before raising anything. Limiting per user or API key is usually fairer than per IP.