Implementing Robust Retry Logic: axios-retry vs fetch-retry vs node-fetch-retry

Network requests fail. Sometimes it's a blip in the connection, sometimes the server is overwhelmed. In production apps, simply giving up after one failure is rarely an option. We need retry logic.

The JavaScript ecosystem offers three main contenders for this job: axios-retry, fetch-retry, and the now-defunct node-fetch-retry. While they all solve the same problem, they fit into different architectural stacks. Let's break down how they work, where they shine, and why one of them should be avoided entirely.

🏗️ Core Architecture: Plugin vs Wrapper vs Deprecated

The fundamental difference lies in how these tools attach to your HTTP client.

axios-retry acts as an interceptor plugin. It hooks directly into axios's internal request/response cycle. It doesn't wrap the function call; instead, it registers logic that runs automatically whenever axios makes a request. This allows it to access deep internal state, like unique request IDs.

// axios-retry: Attaches via interceptors
import axios from 'axios';
import axiosRetry from 'axios-retry';

axiosRetry(axios, {
  retries: 3,
  retryCondition: (error) => {
    return axiosRetry.isNetworkOrIdempotentRequestError(error);
  }
});

// Usage remains standard axios
axios.get('https://api.example.com/data');

fetch-retry acts as a function wrapper. It takes the native fetch function (or node-fetch) and returns a new function that looks and feels exactly like fetch, but with retry logic baked in. You explicitly create this wrapped version and use it instead of the global fetch.

// fetch-retry: Wraps the fetch function
import fetchRetry from 'fetch-retry';

const fetchWithRetry = fetchRetry(fetch);

// Usage uses the wrapped function
fetchWithRetry('https://api.example.com/data', {
  retries: 3,
  retryDelay: 1000
})
  .then(response => response.json());

node-fetch-retry was historically a wrapper specifically for the node-fetch package in Node.js environments. However, this package is deprecated. The maintainers have archived it, and it is no longer receiving updates. Using it introduces security risks and technical debt. You should treat it as obsolete.

// node-fetch-retry: DEPRECATED - Do not use
// import fetchRetry from 'node-fetch-retry'; 
// ❌ This package is unmaintained. Switch to 'fetch-retry' instead.

⏱️ Controlling Delay Strategies

When a request fails, you rarely want to retry immediately. Hammering a struggling server can make things worse. All active packages support custom delay strategies, but the implementation differs slightly.

axios-retry provides a retryDelay option that can be a fixed number or a function. The function receives the retry count, letting you implement exponential backoff easily.

// axios-retry: Custom delay function
axiosRetry(axios, {
  retryDelay: (retryCount) => {
    // Exponential backoff: 1s, 2s, 4s...
    return retryCount * 1000; 
  }
});

fetch-retry offers the same flexibility via its configuration object passed during the wrapper creation or the individual call. It also supports a function for dynamic delays.

// fetch-retry: Custom delay function
const fetchWithRetry = fetchRetry(fetch, {
  retryDelay: (attemptIndex) => {
    return Math.pow(2, attemptIndex) * 1000; // Exponential backoff
  }
});

Both approaches allow you to tailor the timing to your server's recovery characteristics. The syntax is nearly identical, making migration between them (if switching HTTP clients) straightforward regarding delay logic.

🎯 Deciding When to Retry

Not all errors deserve a retry. A 404 Not Found won't fix itself if you try again. A 503 Service Unavailable might. Defining the "retry condition" is critical.

axios-retry shines here with built-in helpers. It includes isNetworkOrIdempotentRequestError, which automatically handles common cases like network errors or safe HTTP methods (GET, HEAD, OPTIONS). You can also write your own logic based on the error object.

// axios-retry: Built-in helper + custom logic
axiosRetry(axios, {
  retryCondition: (error) => {
    // Use built-in check OR custom status code check
    return axiosRetry.isNetworkOrIdempotentRequestError(error) || 
           error.response?.status === 429; // Retry on Rate Limit
  }
});

fetch-retry requires you to define the logic explicitly, as it operates on the standard Response or Error objects. It doesn't ship with named helpers, so you check the status or network state directly.

// fetch-retry: Explicit logic
const fetchWithRetry = fetchRetry(fetch, {
  retryOn: (attempt, error, response) => {
    if (attempt >= 3) return false; // Stop after 3 tries
    if (error !== null) return true; // Network error
    if (response && response.status === 429) return true; // Rate limited
    return false;
  }
});

While axios-retry offers a slight convenience with its helper functions, fetch-retry's explicit approach gives you full transparency into exactly what is being checked.

🆔 Tracking Requests and Idempotency

In complex systems, you might need to know if a request is a retry to handle idempotency keys or logging correctly.

axios-retry automatically attaches a retryCount property to the request config and can inject a custom header (like X-Request-ID) that persists across retries. This is vital for backend tracing.

// axios-retry: Automatic request ID injection
axiosRetry(axios, {
  retryCondition: (error) => {
    const config = error.config;
    if (!config) return false;
    
    // Access how many times this specific request has retried
    console.log(`Retry attempt: ${config['axios-retry'].retryCount}`);
    return true;
  },
  // Automatically add header to identify the request across retries
  onRetry: (retryCount, error, requestConfig) => {
    requestConfig.headers['X-Retry-Count'] = retryCount;
  }
});

fetch-retry does not have built-in request ID tracking because it wraps the generic fetch API. You must manually manage headers or context if you need to track retry counts across attempts.

// fetch-retry: Manual tracking required
let attempt = 0;

const fetchWithTracking = async (url, options) => {
  const fetchWithRetry = fetchRetry(fetch, {
    onRetry: (attemptIndex, err, response) => {
      // Manually log or modify headers if needed
      console.log(`Retrying request, attempt: ${attemptIndex + 1}`);
    }
  });
  
  return fetchWithRetry(url, options);
};

If your architecture relies heavily on distributed tracing where every retry must carry the same trace ID, axios-retry handles this out of the box with less boilerplate.

🌐 Environment Compatibility

Where can you run these?

axios-retry works wherever axios works. Since axios runs in browsers and Node.js, this plugin is universal. However, it ties you to the axios library.

fetch-retry is truly universal. It works in modern browsers (using native fetch) and in Node.js (using native fetch in v18+ or node-fetch for older versions). It is the most flexible choice for isomorphic codebases that want to avoid axios.

node-fetch-retry was limited to Node.js only. Given its deprecation, it has no place in modern cross-platform development.

📊 Summary: Key Differences

💡 The Big Picture

Choosing the right retry tool depends entirely on your HTTP client strategy.

If your team is already committed to axios, axios-retry is the natural choice. Its deep integration, automatic request ID handling, and helper functions reduce boilerplate and make complex retry scenarios easier to manage. It feels like a native part of the axios ecosystem.

If you prefer standard web APIs and want to keep your bundle size lean, fetch-retry is the superior modern option. It brings robust retry logic to the native fetch without forcing you to adopt a third-party HTTP client. It works everywhere and future-proofs your code as Node.js and browsers converge on native fetch.

Avoid node-fetch-retry completely. It is a relic of a time before native fetch existed in Node.js. Continuing to use it offers no benefits over fetch-retry and introduces significant maintenance risks.

Final Thought: Network instability is a fact of life. Whether you choose the deep features of axios-retry or the standards-based approach of fetch-retry, adding retry logic is a non-negotiable step for building resilient frontend applications. Just make sure you pick the tool that matches your stack—and leave the deprecated ones behind.