Retry Failed API Requests with TypeScript

Retrying a failed API request means catching the error, waiting, and trying again. In TypeScript, you can build a typed retry wrapper that preserves the response type through every attempt. The caller gets back the same typed result whether the function succeeded on the first try or the fifth.

The wrapper needs three things: a decision about which errors are retryable, a waiting strategy between attempts, and a limit on how many times to try.

A Basic Typed Retry Wrapper

Start with a simple wrapper that retries a function a fixed number of times, waiting between each attempt.

typescript

async function withRetry<T>(
  fn: () => Promise<T>,
  maxAttempts: number
): Promise<T> {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (attempt === maxAttempts) throw error;
      await new Promise((resolve) => setTimeout(resolve, 1000 * attempt));
    }
  }
  throw new Error("Unreachable");
}

The generic type T preserves whatever the inner function returns. If fn returns a Promise of User, withRetry returns a Promise of User. The type flows through untouched.

The wait time increases with each attempt: one second before the second try, two seconds before the third, and so on. This is linear backoff. Exponential backoff is better for production use.

Deciding Which Errors to Retry

Not every error should trigger a retry. A 404 means the resource does not exist, so retrying will not help. A 503 means the server is temporarily overloaded, so waiting and retrying might succeed.

typescript

function shouldRetry(error: unknown): boolean {
  if (error instanceof ApiError) {
    return error.status >= 500 || error.status === 429;
  }
  return true;
}

Server errors and rate limits are retryable. Client errors are not. Network errors that are not ApiError instances should also be retried, since they are usually transient. The ApiError class here is a custom error that carries the HTTP status code.

Exponential Backoff with Jitter

Exponential backoff doubles the wait time after each attempt. Jitter adds randomness to prevent many clients from retrying at exactly the same moment.

typescript

function getDelay(attempt: number): number {
  const base = Math.pow(2, attempt) * 100;
  const jitter = Math.random() * 100;
  return base + jitter;
}

The wait times are roughly 200ms, 400ms, 800ms, 1600ms, with up to 100ms of random jitter added to each. This spreads out retry attempts from multiple clients.

The diagram shows the retry loop. The function is called, and if it fails, the wrapper checks whether the error is retryable and whether attempts remain. If both conditions pass, it waits and tries again.

The Complete Typed Retry Wrapper

Combining all the pieces produces a production-ready retry function.

First, define a configuration interface so callers can customize the retry behavior explicitly.

typescript

interface RetryConfig {
  maxAttempts: number;
  baseDelayMs: number;
  shouldRetry: (error: unknown) => boolean;
}

The config object makes max attempts, delay timing, and retry decisions explicit. Callers can adjust behavior per endpoint without touching the wrapper code. A small wait helper turns a delay into an awaitable pause:

typescript

function wait(ms: number): Promise<void> {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

Now build the wrapper that uses exponential backoff with jitter. It loops up to maxAttempts times, returning immediately on success. On failure, it throws right away if the error is not retryable or attempts are exhausted, otherwise it waits before the next attempt:

typescript

async function withRetry<T>(
  fn: () => Promise<T>,
  config: RetryConfig
): Promise<T> {
  for (let attempt = 0; attempt < config.maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (attempt === config.maxAttempts - 1 || !config.shouldRetry(error)) throw error;
      await wait(Math.pow(2, attempt) * config.baseDelayMs + Math.random() * config.baseDelayMs);
    }
  }
  throw new Error("Unreachable");
}

Adding AbortController Support

Retries can take a long time. Let callers cancel the entire retry sequence by threading an AbortSignal through the config. The wrapper checks the signal at the start of every attempt with throwIfAborted, and again after a failure before deciding to retry:

typescript

async function withRetry<T>(fn: (signal: AbortSignal) => Promise<T>, config: RetryConfig & { signal?: AbortSignal }): Promise<T> {
  for (let attempt = 0; attempt < config.maxAttempts; attempt++) {
    config.signal?.throwIfAborted();
    try {
      return await fn(config.signal!);
    } catch (error) {
      if (config.signal?.aborted || attempt === config.maxAttempts - 1 || !config.shouldRetry(error)) throw error;
      await wait(Math.pow(2, attempt) * config.baseDelayMs);
    }
  }
  throw new Error("Unreachable");
}

The throwIfAborted check at the start of each iteration lets the caller stop retries immediately. The signal is also passed to fn so individual requests can be aborted, not just the retry loop.

Common Mistakes

Retrying on 4xx errors. A 400, 401, 403, or 404 means the request itself is wrong. Retrying sends the same wrong request again. Fix the request instead of retrying.

Not setting a maximum retry count. Without a limit, a persistent server error causes an infinite loop. Always cap retries at a reasonable number, typically three to five attempts.

Retrying without backoff. Sending retries immediately after a failure gives the server no time to recover and can make the problem worse. Always include a delay between attempts, and increase the delay with each retry.

For the error types used by the retry decision logic, see handle API errors in TypeScript. For cancelling retries in progress, see cancel async requests in TypeScript. For the fetch wrapper being retried, see build a typed fetch wrapper.