HTTP Request Retry Libraries for JavaScript Applications
axios-retry, got, node-fetch-retry, requestretry, retry-axios, and superagent-retry are npm packages that add automatic retry capabilities to HTTP requests in JavaScript applications. They help developers handle transient network failures—such as timeouts, 5xx server errors, or rate-limiting—by reissuing failed requests according to configurable policies. These libraries differ in their integration approach (plugin vs. built-in), supported HTTP clients, configuration flexibility, and maintenance status.
Npm Package Weekly Downloads Trend
Github Stars Ranking
Stat Detail
HTTP Request Retry Strategies in JavaScript: A Deep Dive
When building resilient web applications, handling transient network failures is non-negotiable. The packages axios-retry, got, node-fetch-retry, requestretry, retry-axios, and superagent-retry all aim to automate retry logic for failed HTTP requests — but they differ significantly in architecture, flexibility, and ecosystem alignment. Let’s examine how each approaches retries and when to use which.
🧩 Core Architecture: Standalone vs Plugin vs Built-In
axios-retry is a plugin that extends the popular axios HTTP client using its interceptor system. It doesn’t replace axios; it enhances it.
import axios from 'axios';
import axiosRetry from 'axios-retry';
axiosRetry(axios, { retries: 3 });
// Now all axios requests will retry automatically
await axios.get('/api/data');
retry-axios (often abbreviated rax) also integrates with axios, but uses a different mechanism: it wraps the request in a retry-aware function that can be applied per-call or globally.
import * as rax from 'retry-axios';
import axios from 'axios';
const interceptorId = rax.attach(); // attaches globally
// Or use per-request:
await rax(axios.get('/api/data'), { retry: 3 });
superagent-retry works similarly as a plugin for the superagent HTTP library. You call .retry() on a request chain.
import superagent from 'superagent';
import 'superagent-retry';
await superagent
.get('/api/data')
.retry(3) // retries up to 3 times
.end();
node-fetch-retry wraps the native-like node-fetch API and adds retry options directly to the fetch call.
import fetchRetry from 'node-fetch-retry';
await fetchRetry('/api/data', {
retries: 3,
retryDelay: 1000
});
requestretry is a full replacement for the now-deprecated request library, bundling retry logic into its core API.
import request from 'requestretry';
request({
url: '/api/data',
maxAttempts: 3,
retryDelay: 1000
}, (err, response, body) => {
// handle result
});
got stands apart: retry logic is built directly into its core design. No plugins needed — retries are a first-class feature.
import got from 'got';
await got('/api/data', {
retry: {
limit: 3,
methods: ['GET', 'PUT']
}
});
⚠️ Important: The
requestlibrary (and by extensionrequestretry) has been officially deprecated since February 2020. Whilerequestretrystill functions, it should not be used in new projects due to lack of modern maintenance and reliance on an outdated HTTP client.
🎯 Retry Configuration Granularity
How much control do you get over when and how retries happen?
got offers the most granular control. You can specify:
- Which HTTP methods to retry
- Which status codes trigger retries
- Custom retry conditions via functions
- Exponential backoff with jitter
await got('/api/data', {
retry: {
limit: 3,
methods: ['GET', 'HEAD'],
statusCodes: [408, 413, 429, 500, 502, 503, 504],
calculateDelay: ({ attemptCount }) => Math.pow(2, attemptCount) * 1000
}
});
axios-retry allows custom retry conditions via the retryCondition option and supports exponential backoff through retryDelay.
axiosRetry(axios, {
retries: 3,
retryCondition: (error) => {
return error.response?.status === 503;
},
retryDelay: axiosRetry.exponentialDelay
});
retry-axios provides similar configurability, including custom retry logic and delay strategies.
await rax(axios.get('/api/data'), {
retry: 3,
noResponseRetries: 2,
httpMethodsToRetry: ['GET', 'HEAD'],
statusCodesToRetry: [[100, 199], [429, 429], [500, 599]]
});
superagent-retry is more limited — it retries on network errors and specific status codes (5xx by default), but customization requires overriding internal methods.
superagent
.get('/api/data')
.retry(3, [500, 502, 503]) // only these statuses
.end();
node-fetch-retry supports basic options like retries, retryDelay, and retryOn, but lacks deep customization.
fetchRetry('/api/data', {
retries: 3,
retryOn: (attempt, error, response) => response?.status === 503
});
requestretry allows setting maxAttempts, retryDelay, and retryStrategy, but again, this is built on a deprecated foundation.
🔄 Backoff Strategies
All packages support some form of delay between retries, but implementation varies.
got: Full control viacalculateDelayfunction; includes built-inbackoffoption.axios-retry: ProvidesexponentialDelay,linearDelay, or custom functions.retry-axios: Uses exponential backoff by default; configurable viacurrentRetryAttempt.superagent-retry: Simple linear delay; no built-in exponential strategy.node-fetch-retry: Accepts staticretryDelayor a function(retryNumber) => delay.requestretry: SupportsretryDelayandretryDelayMultiplierfor exponential behavior.
🌐 Ecosystem Alignment
Your choice often depends on your existing HTTP client:
- Already using
axios? → Chooseaxios-retry(more widely adopted) orretry-axios(more Google-centric). - Using
superagent? →superagent-retryis your only real option. - Prefer native
fetch? →node-fetch-retrygives you retry logic while keeping a familiar API. - Starting fresh or want maximum control? →
gotis purpose-built for robust HTTP interactions with retries as a core concern. - Still on
request? → Migrate away; do not start new projects withrequestretry.
💡 Real-World Recommendation
- For new projects: Use
gotif you’re in Node.js and need maximum reliability and configurability. It’s actively maintained, modern, and retry logic is deeply integrated. - In an
axios-based frontend/backend:axios-retryis the community standard — simple to set up and well-documented. - If you must use
fetch:node-fetch-retryis acceptable for basic needs, but consider wrappingfetchyourself with a lightweight retry utility if requirements grow. - Avoid:
requestretrydue to its dependency on the deprecatedrequestlibrary. Also avoid mixing multiple retry strategies across your codebase — pick one HTTP client and stick with its retry solution.
📊 Summary Table
| Package | Type | HTTP Client | Custom Conditions | Backoff Control | Active Maintenance |
|---|---|---|---|---|---|
axios-retry | Plugin | axios | ✅ | ✅ (predefined + custom) | ✅ |
retry-axios | Wrapper | axios | ✅ | ✅ | ✅ |
superagent-retry | Plugin | superagent | ⚠️ (limited) | ❌ (basic only) | ✅ |
node-fetch-retry | Wrapper | node-fetch | ✅ (basic) | ✅ (simple) | ✅ |
requestretry | Full client | request (deprecated) | ✅ | ✅ | ❌ (avoid) |
got | Built-in | got | ✅ (full) | ✅ (advanced) | ✅ |
🔚 Final Thought
Retry logic seems simple until you’re debugging why a critical API call failed silently in production. The right tool gives you visibility, control, and confidence. If you’re already invested in an HTTP client like axios, extend it with its ecosystem’s retry package. But if you’re choosing from scratch — especially for backend services where reliability is paramount — got’s thoughtful, integrated approach makes it the strongest choice today.
How to Choose: axios-retry vs got vs node-fetch-retry vs requestretry vs retry-axios vs superagent-retry
- axios-retry:
Choose
axios-retryif you're already usingaxiosand want a widely adopted, easy-to-integrate retry plugin that leverages axios interceptors. It supports custom retry conditions and built-in delay strategies like exponential backoff, making it suitable for both frontend and Node.js environments where axios is the standard HTTP client. - got:
Choose
gotif you're starting a new Node.js project and need a modern, full-featured HTTP client with retry logic built directly into its core. It offers the most granular control over retry conditions, status codes, methods, and backoff strategies, and is actively maintained with a focus on reliability and developer experience. - node-fetch-retry:
Choose
node-fetch-retryif you prefer using afetch-like API in Node.js and need basic retry functionality without switching HTTP clients. It’s a lightweight wrapper aroundnode-fetchthat adds retry options, but lacks the advanced customization found in more specialized libraries likegot. - requestretry:
Do not choose
requestretryfor new projects. It extends therequestlibrary, which has been officially deprecated since 2020. While it may still work, it lacks modern maintenance, security updates, and compatibility with current Node.js best practices. Migrate existing usage to alternatives likegotoraxioswith retry plugins. - retry-axios:
Choose
retry-axios(also known asrax) if you're in a Google Cloud or TypeScript-heavy environment and need fine-grained control over axios retries, including per-request configuration and detailed status code ranges. It’s a solid alternative toaxios-retry, though slightly less common in the broader ecosystem. - superagent-retry:
Choose
superagent-retryonly if your project already relies on thesuperagentHTTP library and you need simple retry logic. It integrates cleanly via method chaining but offers limited customization for retry conditions and backoff strategies compared to more flexible alternatives.
Popular Comparisons
README for axios-retry
axios-retry
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
| Name | Type | Default | Description |
|---|---|---|---|
| retries | Number | 3 | The number of times to retry before failing. 1 = One retry after first failure |
| retryCondition | Function | isNetworkOrIdempotentRequestError | A 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). |
| shouldResetTimeout | Boolean | false | Defines if the timeout should be reset between retries |
| retryDelay | Function | function 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. |
| onRetry | Function | function 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. |
| onMaxRetryTimesExceeded | Function | function onMaxRetryTimesExceeded(error, retryCount) { return; } | After all the retries are failed, this callback will be called with the last error before throwing the error. |
| validateResponse | Function | null | null | A 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
- Fork it:
git clone https://github.com/softonic/axios-retry.git - Create your feature branch:
git checkout -b feature/my-new-feature - Commit your changes:
git commit -am 'Added some feature' - Check the build:
npm run build - Push to the branch:
git push origin my-new-feature - Submit a pull request :D