Timeouts and retries for flaky requests

Understanding Timeouts and retries for flaky requests

A promise has no concept of "too long". When you await a request, your async function stays suspended until that promise settles, so a socket that hangs open produces a promise that never settles and code that never resumes; no error is thrown because nothing failed. A deadline therefore has to come from outside the request: you start a second promise that rejects on a timer and race it against the first, and whichever settles first decides what your code sees.

Racing ends your wait, not the work. The request keeps running, the server keeps processing it, and the connection stays occupied, which is why an unconditional retry of a POST can apply the same operation twice. Passing an AbortSignal into the request and aborting it when the deadline fires is the only thing that closes the socket, so the timeout wrapper and the cancellation mechanism are two separate jobs that belong together.

Retries buy you a second chance at the cost of latency, so they need boundaries on both ends. Retry the failures that a different moment can fix, such as a connection reset, a 429, or a 502/503/504, and rethrow immediately on a 400 or 404 that will answer identically forever, and on your own TypeError, which retrying only delays. Then think in budgets: attempts multiplied by the per-attempt timeout plus the backoff waits is the worst-case delay a user sits through, and exponential backoff with jitter keeps a crowd of clients from retrying in lockstep against a server that is already struggling.

The mental model is two nested clocks. The inner clock bounds one attempt; the outer clock bounds the whole operation, including sleeps, and both must be explicit or the operation is unbounded in practice.

let calls = 0;

// Stand-in for a flaky endpoint: the first call hangs, later calls are fast.
function fetchQuote() {
  const n = ++calls;
  return new Promise((resolve) => {
    setTimeout(() => resolve(`quote #${n}`), n === 1 ? 500 : 20);
  });
}

function withTimeout(promise, ms) {
  let timer;
  const deadline = new Promise((_, reject) => {
    timer = setTimeout(() => reject(new Error(`timed out after ${ms}ms`)), ms);
  });
  return Promise.race([promise, deadline]).finally(() => clearTimeout(timer));
}

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

async function retry(task, { attempts = 3, timeoutMs = 100, base = 50 } = {}) {
  let lastError;
  for (let i = 1; i <= attempts; i++) {
    try {
      const value = await withTimeout(task(), timeoutMs);
      console.log(`attempt ${i}: ok`);
      return value;
    } catch (err) {
      lastError = err;
      console.log(`attempt ${i} failed: ${err.message}`);
      if (i < attempts) await sleep(base * 2 ** (i - 1));
    }
  }
  throw new Error(`all ${attempts} attempts failed`, { cause: lastError });
}

retry(fetchQuote).then((quote) => console.log('got:', quote));

Worked examples

function slowRequest(signal) {
  return new Promise((resolve, reject) => {
    const id = setTimeout(() => {
      console.log('server work finished');
      resolve('data');
    }, 300);

    signal.addEventListener('abort', () => {
      clearTimeout(id);
      console.log('work stopped at the source');
      reject(signal.reason);
    });
  });
}

const controller = new AbortController();
setTimeout(() => controller.abort(new Error('deadline exceeded')), 100);

slowRequest(controller.signal)
  .then((data) => console.log('resolved:', data))
  .catch((err) => console.log('rejected:', err.message));

class HttpError extends Error {
  constructor(status) {
    super(`HTTP ${status}`);
    this.status = status;
  }
}

function isRetryable(err) {
  if (err instanceof HttpError) return err.status === 429 || err.status >= 500;
  return true; // no status: a network-level failure, worth another try
}

const failWith = (status) => () => Promise.reject(new HttpError(status));

async function retry(task, attempts = 3) {
  for (let i = 1; i <= attempts; i++) {
    try {
      return await task();
    } catch (err) {
      if (!isRetryable(err) || i === attempts) {
        console.log(`${err.message}: stopped after ${i} attempt(s)`);
        return;
      }
      console.log(`${err.message}: attempt ${i} failed, retrying`);
    }
  }
}

(async () => {
  await retry(failWith(503));
  await retry(failWith(404));
})();

function backoff(attempt, { base = 100, cap = 1000 } = {}) {
  return Math.min(cap, base * 2 ** (attempt - 1));
}

let total = 0;
for (let attempt = 1; attempt <= 6; attempt++) {
  const wait = backoff(attempt);
  total += wait;
  console.log(`after attempt ${attempt}: wait ${wait}ms (total ${total}ms)`);
}

Important notes

Common mistakes

Try it yourself