fetch with timeout, retries, and exponential backoff

Plain fetch() waits as long as the network lets it and gives up after a single failure. Real clients need a timeout and a polite retry strategy. This module adds both without any dependencies.

The script

Save it as fetch-retry.mjs. It needs Node.js 20.3 or newer (for AbortSignal.any) or a current browser. Run it directly with a URL, or import fetchWithRetry into your own code.

// fetch-retry.mjs - fetch with a timeout, retries, and exponential backoff.
// Needs Node.js 20.3+ or a current browser. Usage: node fetch-retry.mjs URL

const RETRYABLE_STATUS = new Set([408, 429, 500, 502, 503, 504]);
const IDEMPOTENT = new Set(["GET", "HEAD", "OPTIONS", "PUT", "DELETE"]);

function sleep(ms, signal) {
  return new Promise((resolve, reject) => {
    const timer = setTimeout(resolve, ms);
    signal?.addEventListener("abort", () => {
      clearTimeout(timer);
      reject(signal.reason);
    }, { once: true });
  });
}

function retryAfterMs(response) {
  const value = response.headers.get("Retry-After");
  if (!value) return null;
  const seconds = Number(value);
  if (Number.isFinite(seconds)) return Math.max(0, seconds * 1000);
  const date = Date.parse(value);
  return Number.isNaN(date) ? null : Math.max(0, date - Date.now());
}

export async function fetchWithRetry(url, options = {}) {
  const {
    retries = 3,
    timeoutMs = 5000,
    baseDelayMs = 300,
    maxDelayMs = 5000,
    retryUnsafe = false,
    signal,
    ...init
  } = options;
  const method = (init.method || "GET").toUpperCase();
  const canRetry = IDEMPOTENT.has(method) || retryUnsafe;

  for (let attempt = 0; ; attempt++) {
    const attemptSignal = signal
      ? AbortSignal.any([signal, AbortSignal.timeout(timeoutMs)])
      : AbortSignal.timeout(timeoutMs);

    let response;
    let error;
    try {
      response = await fetch(url, { ...init, method, signal: attemptSignal });
    } catch (err) {
      if (signal?.aborted) throw err;
      error = err;
    }

    const retryable = error || RETRYABLE_STATUS.has(response.status);
    if (!retryable || !canRetry || attempt >= retries) {
      if (error) throw error;
      return response;
    }

    const backoff = Math.min(maxDelayMs, baseDelayMs * 2 ** attempt);
    const jittered = Math.random() * backoff;
    const wait = (response && retryAfterMs(response)) ?? jittered;
    const reason = error ? error.name : `HTTP ${response.status}`;
    console.error(`attempt ${attempt + 1} failed (${reason}); retrying in ${Math.round(wait)} ms`);
    await response?.body?.cancel();
    await sleep(Math.min(wait, maxDelayMs), signal);
  }
}

const runDirectly = typeof process !== "undefined" && process.argv?.[1] &&
  import.meta.url === new URL(`file://${process.argv[1]}`).href;

if (runDirectly) {
  const url = process.argv[2] ?? "http://127.0.0.1:8765/";
  const response = await fetchWithRetry(url, { retries: 4, timeoutMs: 2000 });
  console.log(response.status, response.statusText);
  console.log(await response.text());
}

node fetch-retry.mjs http://127.0.0.1:8765/status/503

Design decisions

• Per-attempt timeout. AbortSignal.timeout() aborts a request that hangs. Each attempt gets a fresh timeout, so a slow first try does not eat the whole budget.
• Caller cancellation wins. If you pass your own signal and abort it, the function stops immediately instead of retrying. AbortSignal.any() combines the two signals.
• Only retry what is safe. Network errors and the statuses 408, 429, 500, 502, 503, and 504 are retried. Other 4xx codes mean the request itself is wrong, so retrying would only repeat the failure.
• Only retry idempotent methods. Repeating a POST could create a duplicate order. Pass retryUnsafe: true only when your API supports idempotency keys or similar protection.
• Backoff with full jitter. The delay ceiling doubles each attempt (300 ms, 600 ms, 1200 ms, and so on, capped at maxDelayMs), and the actual delay is random below that ceiling. Randomness keeps many clients from retrying in lockstep after an outage.
• Retry-After is respected. Servers send it with 429 and 503 to say when to come back, as seconds or an HTTP date. The wait is still capped so a huge value does not stall your app.
• Release the body. Cancelling the unused response body before retrying lets the connection be reused or freed.

Using it in your code

import { fetchWithRetry } from "./fetch-retry.mjs";

const controller = new AbortController();
const response = await fetchWithRetry("https://api.example.com/items", {
  headers: { Accept: "application/json" },
  retries: 3,
  timeoutMs: 4000,
  signal: controller.signal,
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const items = await response.json();

Note that the function returns the final response even when it is an error status, just like fetch(). Check response.ok yourself. A timeout surfaces as an error named TimeoutError; a manual abort surfaces as AbortError or whatever reason you passed to abort().

Log lines go to console.error. In a library you would usually replace that with an onRetry callback so the caller decides what to log.