Every API you integrate with eventually rate limits you, and how your client handles that moment says a lot about whether your integration survives a traffic spike gracefully or falls over entirely. A naive client either ignores the 429 and keeps hammering the endpoint, making the underlying problem worse for everyone sharing that API, or gives up entirely and surfaces a raw error to a user who did nothing wrong. Neither outcome is necessary. Here's how to build a retry path that actually respects the limit instead of fighting it.
Step 1: Detect the 429 and Read the Headers
Before writing any retry logic, make sure your HTTP client is actually surfacing rate limit responses distinctly instead of treating them as a generic failure lumped in with every other non-2xx status. A 429 status code should be checked explicitly in your error handling path, and if the API sends a Retry-After header, that value is the source of truth for how long to wait, not a number you guess at or hardcode. The MDN reference on rate limit headers covers the common conventions if the API's own documentation is thin on this particular detail.
Some APIs send the wait time in seconds, others as an HTTP date. Handle both formats, since assuming one and getting the other will produce either an immediate retry that trips the limit again or an unnecessarily long wait that hurts your own user experience for no reason.
Step 2: Implement Exponential Backoff as the Fallback
Not every API sends Retry-After, and plenty of older or simpler APIs just return a bare 429 with no guidance at all. When it doesn't, exponential backoff is the standard fallback: wait a base interval, then double it on each subsequent failure, up to a reasonable cap so a persistent outage doesn't turn into an hours-long wait before your client gives up. This avoids the failure mode where a client retries immediately, gets throttled again immediately, and effectively keeps hammering the API it's trying to be polite to.
A typical starting point is a base delay of one second, doubling on each retry, capped somewhere around thirty to sixty seconds depending on how time-sensitive the calling code actually is.
Step 3: Add Jitter So Retries Don't Synchronize
If you have many client instances, many parallel requests, or many users of a shared library all backing off on the same deterministic schedule, they can end up retrying in lockstep, creating a new burst exactly when the server expected load to have dropped off. Adding random jitter to the backoff interval, even a modest percentage of the base delay, spreads retries out across a wider window and avoids this synchronized-retry problem entirely without meaningfully changing the average wait time.
Step 4: Cap the Total Retry Attempts
An unbounded retry loop is its own outage waiting to happen, especially if the underlying issue isn't transient but something like a revoked API key or a permanently misconfigured endpoint. Set a maximum number of attempts, typically somewhere between three and six depending on how critical the call is, and when that cap is hit, fail the request cleanly and let the calling code decide what happens next, whether that's queuing the work for later or surfacing a real error to a human.
Step 5: Distinguish Retryable From Non-Retryable Failures
A 429 is retryable by definition, that's what the status code means. A 401 or a 400 is not, and retrying either one just wastes time on both ends and, at high enough volume, can itself start to look like abuse to the API you're calling. Make sure your retry wrapper only engages for the status codes that actually mean "try again later," typically 429 and sometimes 503, not every non-2xx response it happens to encounter.
Step 6: Queue Instead of Block for Background Work
For background jobs, batch syncs, and anything not blocking a live user interaction in real time, it's often better to push the rate-limited request onto a queue with its own backoff schedule rather than blocking a worker thread on a sleep call. Redis-backed job queues handle this pattern well, letting you retry asynchronously without tying up application resources or worker capacity that could be doing other useful work in the meantime.
Step 5.5: Understand the Algorithm Producing the 429 You're Handling
It helps to know, at least roughly, what kind of limiter is on the other end of the request you're retrying, since it changes how aggressive your backoff needs to be. A server using a token bucket will often accept a retry successfully within a second or two once the bucket refills slightly. A server using a hard fixed window might not accept anything until the window fully resets, which can be up to a full minute away depending on when in the window your request landed. If the API's documentation says which approach it uses, let that inform your base backoff interval instead of picking one arbitrarily.
Step 7: Log Rate Limit Events Separately From Errors
A 429 handled correctly by your retry logic isn't really an error, it's expected behavior working exactly as designed by both sides. Logging it at error severity generates noise in your monitoring and gradually desensitizes your team to alerts that actually matter. Log it distinctly instead, with enough context, endpoint, retry count, eventual outcome, to spot a client that's consistently running into limits over time, which is a signal worth investigating even if every individual retry eventually succeeded on its own.
Step 8: Test the Path, Not Just the Happy Path
It's easy to write retry logic and never actually exercise it until production traffic does it for you the hard way. Mock a 429 response with a Retry-After header in your test suite and confirm the client waits the right amount of time, retries the right number of times, and eventually gives up cleanly if the server keeps rejecting every attempt. This is exactly the kind of code that looks correct on a read-through and behaves differently under real, messy conditions.
Applying This to Third-Party SDKs You Don't Control
If you're calling an API through a third-party SDK rather than raw HTTP requests, check whether it already implements retry and backoff before building your own layer on top of it. Wrapping an SDK that already retries internally with another retry layer can compound delays in confusing ways, so read the SDK's source or documentation first rather than assuming you need to reinvent this from scratch.
A Minimal Checklist Before You Ship This
Before merging retry logic like this, walk through a short checklist: does it check the actual status code rather than any non-2xx response, does it respect Retry-After when present, does it fall back to exponential backoff with jitter when the header is absent, does it cap total attempts, and does it log rate-limit events at a severity that won't drown out real errors. Five short questions, but between them they cover almost every mistake that shows up in retry code written under time pressure right before a launch.
Handled well, a 429 becomes a normal, unremarkable part of your client's operating range instead of an incident that pages someone at 2am. If you're building this on the server side instead and want the deeper reasoning behind algorithm choice, key selection, and header design that produces the 429s your client is reacting to, the team at 137Foundry wrote up a full guide to designing a rate limiter that doesn't punish real users that pairs well with this client-side piece.
Top comments (0)