Retrying failed API calls: backoff, jitter and Retry-After
Short answer: When your app calls another service, such as a payment provider, a shipping API or a CRM, some requests will fail for reasons that fix themselves within seconds. Retry those, but not straight away and not forever: wait a little longer after each attempt (exponential backoff), add randomness so many clients do not retry in lockstep (jitter), respect a Retry-After header when the server sends one, and cap the number of attempts. Only retry requests that are safe to repeat.
Why naive retries make things worse
A retry loop that tries again immediately, as fast as it can, feels helpful. In practice it turns a short wobble into an outage. If a supplier's API is struggling under load and every client hammers it again within milliseconds, the load doubles at exactly the wrong moment. Your own app also ties up workers and connections waiting on calls that keep failing.
The fix is to slow down on purpose. Each failed attempt should increase the wait before the next one, so pressure on the struggling service falls rather than rises.
Which failures deserve a retry
Not every error is temporary. Before writing any retry logic, sort failures into two groups:
- Worth retrying: timeouts, dropped connections, 429 Too Many Requests, 502, 503 and 504 responses. These usually mean "busy" or "briefly unreachable".
- Not worth retrying: most other 4xx responses, such as 400, 401, 403, 404 and 422. Sending the same bad request again will produce the same answer. Fix the request, refresh the credentials or log the problem instead.
Also think about what the request does. HTTP's core specification, RFC 9110, defines a method as idempotent when sending several identical requests has the same intended effect as sending one. GET, PUT and DELETE are defined that way; POST is not. Retrying a POST that creates an order or takes a payment can create duplicates, unless the API supports an idempotency key that lets the server recognise a repeat. If it does not, do not retry those calls automatically.
Exponential backoff in plain terms
Exponential backoff means the delay grows with each attempt, typically doubling: wait about one second, then two, then four, then eight, up to a ceiling such as 30 or 60 seconds. You also set a maximum number of attempts, often between three and six for an interactive request and more for a background job.
The ceiling matters. Without it, delays grow absurdly large; without an attempt limit, a permanent failure keeps retrying forever and hides the real problem.
Add jitter
Backoff alone still has a weakness. If a hundred clients all fail at the same moment, they will all wait one second, then all retry together, then all wait two seconds and retry together again. The retries arrive in waves.
Jitter spreads them out by adding randomness to each delay. An article on the AWS Architecture Blog, "Exponential Backoff and Jitter", compares several approaches: "Full Jitter", where each wait is a random value between zero and the current backoff ceiling; "Equal Jitter", which keeps part of the backoff and randomises the rest; and "Decorrelated Jitter", which grows the maximum based on the previous random value. The article's simulations favour adding jitter over plain backoff, because randomised clients collide far less. For most small apps, full jitter is the simplest choice that works well.
Respect Retry-After
Sometimes the server tells you exactly how long to wait. RFC 9110 defines the Retry-After header, whose value is either an HTTP date or a number of seconds to delay. RFC 6585, which defines the 429 Too Many Requests status, says such responses may include a Retry-After header indicating how long to wait before making a new request, and its example uses Retry-After: 3600.
When the header is present, use it in place of your own calculation, as long as it falls within a limit you can live with. If an API tells an interactive request to wait an hour, it is better to fail fast with a clear message than to leave a customer staring at a spinner.
Where the retry logic should live
- Interactive requests, such as a customer clicking "check delivery options", should retry briefly, perhaps twice, then fall back gracefully: show a sensible message, use cached data or let the order continue with a later update.
- Background jobs, such as syncing orders to an accounting system overnight, can afford longer backoff and more attempts. Your job queue may already offer retries with backoff as a setting.
- Shared HTTP clients are the best place to put the logic once, so every integration behaves the same way, rather than copying a loop into each function.
Log every retry with the attempt number, the status code and the wait chosen. Those logs are how you discover that a supplier's API has been flaky every Monday morning.
A worked example
Take a hypothetical Denver outdoor-gear store that sends each paid order to a third-party warehouse API. During a sale, the warehouse returned 503 errors for a few minutes. The store's code retried each failed call instantly, ten times. Hundreds of orders multiplied into thousands of requests, the warehouse started returning 429 responses with a Retry-After header, and some orders were sent twice because the create-shipment call had no idempotency key.
The fix had four parts: retry only timeouts, 429 and 5xx responses; use exponential backoff with full jitter, capped at 60 seconds and five attempts; follow Retry-After when present; and send an idempotency key with each shipment request, which the warehouse API supported. Orders that still failed went to a review list instead of vanishing.
FAQ
How many retries are reasonable?
For a request a person is waiting on, two or three. For a background job, more is fine, as long as there is a cap and failures end up somewhere visible.
Should I retry on a 500 Internal Server Error?
Sometimes. A 500 can be temporary or a genuine bug. Retry once or twice with backoff, then stop and log it.
Do I need a library for this?
Not necessarily, but many HTTP clients and job queues include retry and backoff options. Using a tested one is usually safer than writing your own loop.
What is a circuit breaker?
A pattern that stops calling a failing service for a while after repeated errors, then tests it again. It complements retries for integrations that go down for longer periods.
If your integrations fall over whenever a partner API has a bad few minutes, tell us which services your app talks to.