axios-retry vs fetch-retry vs got vs retry-axios vs superagent-retry
Implementing Robust HTTP Retry Logic in JavaScript Applications
axios-retryfetch-retrygotretry-axiossuperagent-retrySimilar Packages:

Implementing Robust HTTP Retry Logic in JavaScript Applications

This comparison evaluates five npm packages designed to handle transient network failures by automatically retrying failed HTTP requests. axios-retry and retry-axios are plugins specifically for the Axios library, offering different levels of control and maintenance status. fetch-retry wraps the native fetch API to add retry capabilities without replacing the underlying client. got is a complete, human-friendly HTTP client for Node.js with built-in retry logic. superagent-retry extends the Superagent library, though both the plugin and its parent library face significant maintenance challenges. These tools help developers build resilient applications that can recover from temporary network glitches, 5xx server errors, or rate limiting without manual intervention.

Npm Package Weekly Downloads Trend

3 Years

Github Stars Ranking

Stat Detail

Package
Downloads
Stars
Size
Issues
Publish
License
axios-retry02,01033.6 kB582 years agoApache-2.0
fetch-retry031855.2 kB63 years agoMIT
got014,957495 kB05 days agoMIT
retry-axios051264.9 kB17 months agoApache-2.0
superagent-retry083-1010 years ago-

Implementing Robust HTTP Retry Logic: A Deep Dive into JavaScript Solutions

Network requests fail. It is not a matter of "if," but "when." Whether it is a flaky mobile connection, a temporary server overload (503), or a rate limit (429), professional applications must handle these hiccups gracefully. Relying on manual try...catch loops is error-prone and clutters your business logic.

This analysis compares five specific solutions for automating retries: axios-retry, fetch-retry, got, retry-axios, and superagent-retry. We will look at how they integrate, how they handle timing, and which ones you should actually put into production today.

🏗️ Integration Model: Plugins vs. Built-in vs. Wrappers

The first major difference is how these tools attach to your network layer. Some are plugins for existing clients, one is a built-in feature, and another is a wrapper around the native API.

axios-retry acts as an interceptor plugin. You install it alongside Axios and register it once. It hooks into Axios's internal promise chain.

// axios-retry setup
import axios from 'axios';
import axiosRetry from 'axios-retry';

const client = axios.create();
axiosRetry(client, { retries: 3 });

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

retry-axios also uses the interceptor pattern but attaches to the global Axios instance or a specific one via a slightly different API structure. It modifies the request config before it goes out.

// retry-axios setup
import axios from 'axios';
import { attach } from 'retry-axios';

attach({ axiosInstance: axios });

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

fetch-retry is a wrapper function. It does not modify the global fetch; instead, it returns a new function that you use in place of the native one. This keeps the global scope clean.

// fetch-retry setup
import fetchRetry from 'fetch-retry';
const fetchWithRetry = fetchRetry(fetch);

// Usage replaces native fetch
fetchWithRetry('https://api.example.com/data', { retries: 3 })
  .then(res => res.json());

got requires no plugins. It is a complete HTTP client where retry logic is a core configuration option passed directly into the request.

// got setup (no plugin needed)
import got from 'got';

// Usage includes retry config directly
const response = await got('https://api.example.com/data', {
  retry: { limit: 3 }
});

superagent-retry extends the Superagent request prototype. You call .retry() explicitly on the request chain, similar to how you might call .timeout().

// superagent-retry setup
import request from 'superagent';
import requestRetry from 'superagent-retry';

requestRetry(request);

// Usage chains the retry method
request
  .get('https://api.example.com/data')
  .retry(3)
  .end((err, res) => { /* handle */ });

⏱️ Delay Strategies: Exponential Backoff vs. Fixed Intervals

When a request fails, hammering the server immediately often makes things worse. Good retry logic uses "backoff" — waiting longer between each attempt. Let's see how each package handles this.

axios-retry provides a built-in exponential backoff function but allows you to write your own. This is crucial for respecting rate limits.

// axios-retry: Custom delay calculation
axiosRetry(client, {
  retryDelay: (retryCount) => {
    return retryCount * 1000; // Linear delay: 1s, 2s, 3s
  }
});

retry-axios supports a similar configuration where you define the delay logic based on the attempt number.

// retry-axios: Custom delay
attach({
  axiosInstance: axios,
  retryConfig: {
    retryDelay: (count, error) => {
      return Math.pow(2, count) * 100; // Exponential
    }
  }
});

fetch-retry lets you pass a retryDelay function in the options object. It is straightforward and functional.

// fetch-retry: Custom delay
fetchWithRetry(url, {
  retryDelay: function(attempt) {
    return Math.pow(2, attempt) * 1000;
  }
});

got has a very sophisticated built-in backoff strategy by default (exponential with jitter). You can override it, but the defaults are often sufficient for production use.

// got: Overriding default backoff
got(url, {
  retry: {
    calculateDelay: ({ attemptCount }) => {
      return attemptCount * 500;
    }
  }
});

superagent-retry typically uses a fixed delay or a simple exponential strategy internally, with less flexibility for custom algorithms compared to the Axios plugins.

// superagent-retry: Fixed delay usage
request
  .get(url)
  .retry(3, 1000) // Retries 3 times with 1000ms delay
  .end(callback);

🎯 Filtering: Deciding When to Retry

Not every error deserves a retry. A 404 (Not Found) will never fix itself by trying again. You only want to retry on network errors, 5xx server issues, or 429 (Too Many Requests).

axios-retry exports a helper isNetworkOrIdempotentRequestError but also lets you write a boolean function to decide.

// axios-retry: Custom condition
axiosRetry(client, {
  retryCondition: (error) => {
    // Retry only on 500 errors or network issues
    return error.response?.status === 500 || error.code === 'ECONNRESET';
  }
});

retry-axios uses a similar retryCondition callback in its configuration object.

// retry-axios: Custom condition
attach({
  retryConfig: {
    retryCondition: (error) => {
      return error.config && error.config.method === 'get';
    }
  }
});

fetch-retry provides a retryOn function. Since fetch only rejects on network failure (not HTTP error statuses), you often need to check the response status inside this function.

// fetch-retry: Check response status
fetchWithRetry(url, {
  retryOn: async (attempt, error, response) => {
    if (attempt >= 3) return false;
    if (response && response.status === 503) return true;
    return false;
  }
});

got allows you to specify which HTTP status codes trigger a retry via the statusCodes array, alongside network errors.

// got: Specific status codes
got(url, {
  retry: {
    limit: 3,
    statusCodes: [408, 413, 429, 500, 502, 503, 504]
  }
});

superagent-retry generally retries on network errors and specific server errors by default, but customizing this logic deeply is more verbose than in the Axios ecosystem.

// superagent-retry: Basic usage
// Primarily relies on the count argument; 
// complex filtering often requires manual wrapping
request.get(url).retry(3).end(...);

⚠️ Maintenance Status and Deprecation Warnings

This is the most critical section for architectural decisions. Using unmaintained software introduces security risks and compatibility bugs.

retry-axios has historically suffered from long gaps between releases and issues left unanswered by maintainers. While it still works, the community has largely migrated to axios-retry, which is more actively updated and has broader adoption. Recommendation: Do not start new projects with retry-axios. Use axios-retry instead.

superagent-retry depends on Superagent, a library that has seen a massive decline in usage in favor of Axios and native Fetch. The plugin itself sees very little activity. Recommendation: Avoid for new projects. If you are stuck on Superagent, plan a migration to Axios or Fetch.

axios-retry, fetch-retry, and got are all actively maintained. They receive regular updates to support new Node.js versions, fix security vulnerabilities, and improve TypeScript definitions. These are the safe choices for 2024 and beyond.

🌐 Environment Compatibility: Browser vs. Node.js

Where your code runs dictates which tool you can use.

  • got is Node.js only. It relies on Node-specific streams and HTTP agents. It will not work in a browser bundle without heavy (and often broken) shimming.
  • axios-retry and retry-axios work wherever Axios works: both Browser and Node.js. This makes them perfect for isomorphic applications (code shared between server and client).
  • fetch-retry works in any environment that supports fetch. This includes all modern browsers and Node.js 18+. For older Node versions, you need a polyfill like node-fetch.
  • superagent-retry works in both, but again, the parent library is heavy for browsers compared to native fetch.
// Example: Isomorphic retry with axios-retry
// Works in React (Browser) and Next.js API routes (Node)
import axios from 'axios';
import axiosRetry from 'axios-retry';

const api = axios.create();
axiosRetry(api, { retries: 3 });
export default api;
// Example: Node-only high-performance script with got
// Will crash if imported in a browser bundle
import got from 'got';

async function scrapeData() {
  return await got('https://api.data.com', { retry: { limit: 5 } });
}

📊 Summary Comparison

Featureaxios-retryfetch-retrygotretry-axiossuperagent-retry
Base ClientAxiosNative FetchBuilt-inAxiosSuperagent
EnvironmentBrowser & NodeBrowser & Node (18+)Node OnlyBrowser & NodeBrowser & Node
Setup StylePlugin / InterceptorWrapper FunctionBuilt-in ConfigPlugin / InterceptorPrototype Extension
Custom Delays✅ Full Control✅ Full Control✅ Full Control✅ Full Control⚠️ Limited
Maintenance🟢 Active🟢 Active🟢 Active🟡 Low Activity🔴 Legacy / Low Activity
Bundle SizeMedium (depends on Axios)TinyLarge (Node libs)Medium (depends on Axios)Large

💡 Final Recommendation

Your choice should depend on your existing stack and target environment:

  1. For Modern Node.js Services: Use got. It is the most powerful, has the best developer experience, and requires no extra plugins. Its built-in retry logic is robust and battle-tested.
  2. For React/Frontend or Isomorphic Apps: Use axios-retry. Axios remains the standard for complex frontend HTTP needs (interceptors, cancellation, broad browser support), and this plugin integrates perfectly.
  3. For Lightweight Modern Stacks: Use fetch-retry. If you are done with Axios and want to use the native fetch API, this is the simplest way to add reliability without bloating your bundle.
  4. Avoid: Do not choose retry-axios or superagent-retry for new architecture. The risk of unmaintained dependencies outweighs any minor API preferences they might offer. Stick to the actively maintained leaders in the ecosystem.

How to Choose: axios-retry vs fetch-retry vs got vs retry-axios vs superagent-retry

  • axios-retry:

    Choose axios-retry if your project already relies on Axios and you need a actively maintained, feature-rich plugin. It offers excellent control over retry conditions, custom delays, and works seamlessly in both Node.js and browser environments. It is the standard choice for modern Axios-based stacks requiring robust error recovery.

  • fetch-retry:

    Choose fetch-retry if you prefer using the native fetch API and want to avoid adding a heavy HTTP client like Axios or Got. It is ideal for modern browsers and Node.js 18+ environments where you want lightweight retry logic that simply wraps the existing global fetch function without changing your request syntax significantly.

  • got:

    Choose got if you are building a Node.js-only application and want a powerful, all-in-one HTTP client. Unlike the others, it does not require a separate plugin for retries; the functionality is built-in and highly configurable. It is best for backend services, scripts, and tools where developer experience and comprehensive features are prioritized over bundle size.

  • retry-axios:

    Avoid choosing retry-axios for new projects. While it functions as an interceptor for Axios similar to axios-retry, it has historically suffered from long periods of inactivity and lack of maintenance compared to its competitor. Unless you are maintaining a legacy codebase that strictly depends on it, axios-retry is the safer, more reliable alternative.

  • superagent-retry:

    Avoid choosing superagent-retry for new projects. Both this plugin and its parent library, Superagent, are largely considered legacy in the modern JavaScript ecosystem. They lack the active development and community support found in Axios or native fetch solutions. Migrating to axios-retry or fetch-retry is recommended for better long-term stability.

README for axios-retry

axios-retry

Node.js CI

Axios plugin that intercepts failed requests and retries them whenever possible.

Installation

npm install axios-retry

Usage

// CommonJS
// const axiosRetry = require('axios-retry').default;

// ES6
import axiosRetry from 'axios-retry';

axiosRetry(axios, { retries: 3 });

axios.get('http://example.com/test') // The first request fails and the second returns 'ok'
  .then(result => {
    result.data; // 'ok'
  });

// Exponential back-off retry delay between requests
axiosRetry(axios, { retryDelay: axiosRetry.exponentialDelay });

// Liner retry delay between requests
axiosRetry(axios, { retryDelay: axiosRetry.linearDelay() });

// Custom retry delay
axiosRetry(axios, { retryDelay: (retryCount) => {
  return retryCount * 1000;
}});

// Works with custom axios instances
const client = axios.create({ baseURL: 'http://example.com' });
axiosRetry(client, { retries: 3 });

client.get('/test') // The first request fails and the second returns 'ok'
  .then(result => {
    result.data; // 'ok'
  });

// Allows request-specific configuration
client
  .get('/test', {
    'axios-retry': {
      retries: 0
    }
  })
  .catch(error => { // The first request fails
    error !== undefined
  });

Note: Unless shouldResetTimeout is set, the plugin interprets the request timeout as a global value, so it is not used for each retry but for the whole request lifecycle.

Options

NameTypeDefaultDescription
retriesNumber3The number of times to retry before failing. 1 = One retry after first failure
retryConditionFunctionisNetworkOrIdempotentRequestErrorA callback to further control if a request should be retried. By default, it retries if it is a network error or a 5xx error on an idempotent request (GET, HEAD, OPTIONS, PUT or DELETE).
shouldResetTimeoutBooleanfalseDefines if the timeout should be reset between retries
retryDelayFunctionfunction noDelay() { return 0; }A callback to further control the delay in milliseconds between retried requests. By default there is no delay between retries. Another option is exponentialDelay (Exponential Backoff) or linearDelay. The function is passed retryCount and error.
onRetryFunctionfunction onRetry(retryCount, error, requestConfig) { return; }A callback to notify when a retry is about to occur. Useful for tracing and you can any async process for example refresh a token on 401. By default nothing will occur. The function is passed retryCount, error, and requestConfig.
onMaxRetryTimesExceededFunctionfunction onMaxRetryTimesExceeded(error, retryCount) { return; }After all the retries are failed, this callback will be called with the last error before throwing the error.
validateResponseFunction | nullnullA callback to define whether a response should be resolved or rejected. If null is passed, it will fallback to the axios default (only 2xx status codes are resolved).

Testing

Clone the repository and execute:

npm test

Contribute

  1. Fork it: git clone https://github.com/softonic/axios-retry.git
  2. Create your feature branch: git checkout -b feature/my-new-feature
  3. Commit your changes: git commit -am 'Added some feature'
  4. Check the build: npm run build
  5. Push to the branch: git push origin my-new-feature
  6. Submit a pull request :D