Registry / http-networking / retry-axios

retry-axios

JSON →
library4.0.3jsnpmunverified

retry-axios is a library designed to automatically retry failed HTTP requests made using the Axios client library. It operates as an Axios interceptor, providing built-in exponential backoff and extensive configuration options for retry logic, including HTTP methods, status codes, retry delays, and jitter strategies. The current stable version is 4.0.3, released in April 2026. The package demonstrates a consistent release cadence, with major versions aligning with significant Node.js LTS updates. Key differentiators include its deep integration with Axios interceptors, allowing for global or instance-specific retry policies, and its flexible backoff algorithms (exponential, static, linear) to prevent thundering herd problems, making it suitable for robust client-side network operations in both Node.js and browser environments.

npm install retry-axios
INSTALL
IMPORT
SIG · RETRY-AXIOS
R
retry-axios
http-networkingjavascriptv4.0.3
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

rax
import * as rax from 'retry-axios';
import rax from 'retry-axios';
The library exports a namespace object `rax`. Direct default imports are incorrect and will lead to undefined behavior.
attach
import { attach } from 'retry-axios';
import rax, { attach } from 'retry-axios';
While `attach` is a method on the `rax` object, it can also be directly imported as a named export. The primary usage pattern is via the `rax` namespace.
rax (CommonJS)
const rax = require('retry-axios');
For CommonJS environments, `require('retry-axios')` correctly loads the module. Since v4.0.2, specific declarations were added for nodenext cjs consumers.
AxiosRequestConfig (Type)
import { AxiosRequestConfig } from 'axios'; import { RaxConfig } from 'retry-axios';
When using TypeScript, type definitions for Axios requests are extended with `RaxConfig`. Ensure both Axios and retry-axios types are available in your project.

This quickstart demonstrates how to create a custom Axios instance, configure `retry-axios` for it with specific retry policies (count, delay, status codes, backoff, jitter), and attach the retry interceptor. It includes an `onError` callback for logging and illustrates fetching data from an endpoint that might return a retryable status code, showcasing the retry mechanism in action.

import * as rax from 'retry-axios'; import axios, { AxiosInstance } from 'axios'; interface MyRaxConfig extends rax.RaxConfig { // Optionally extend raxConfig if needed } const myAxiosInstance: AxiosInstance = axios.create(); // Configure retry-axios for this specific instance myAxiosInstance.defaults.raxConfig = { retry: 5, // Retry 5 times retryDelay: 500, // 500ms delay between retries statusCodesToRetry: [[429, 429], [500, 599]], // Only retry for Too Many Requests and 5xx errors backoffType: 'exponential', // Use exponential backoff jitter: 'full', // Add full jitter onError: (err) => { const cfg = rax.getConfig(err); if (cfg) { console.log(`Retry attempt #${cfg.currentRetryAttempt + 1} for URL: ${err.config?.url}`); } } } as MyRaxConfig; // Attach the retry interceptor to the custom instance rax.attach(myAxiosInstance); async function fetchData() { try { // Simulate an API call that might fail and need retries // Using httpbin.org for demonstration purposes. // In a real scenario, this might be a flaky backend endpoint. const response = await myAxiosInstance.get('https://httpbin.org/status/503'); console.log('Successfully fetched data:', response.data); } catch (error: any) { if (error.response) { console.error(`Failed to fetch data after retries. Status: ${error.response.status}`); } else if (error.request) { console.error('Failed to fetch data after retries. No response received.'); } else { console.error('Error during request setup:', error.message); } } } fetchData();
Debug
Known issues
breakingVersion 4.0.0 and above of `retry-axios` require Node.js 20 or higher. Previous versions supported older Node.js runtimes. Ensure your environment meets this minimum version requirement.
fix
Upgrade your Node.js runtime to version 20 or newer. If you must use an older Node.js version, you will need to stick with `retry-axios` v3.x.
affects: >=4.0.0
gotchaWhen importing `retry-axios` with ES Modules, the correct pattern is `import * as rax from 'retry-axios';` because the library exports a namespace object. A direct default import like `import rax from 'retry-axios';` will result in `rax` being undefined or incorrect.
fix
Always use `import * as rax from 'retry-axios';` for ESM imports. For CommonJS, `const rax = require('retry-axios');` is correct.
affects: >=3.0.0
gotcha`retry-axios` can be attached globally to the default `axios` instance or to a specific `axios.create()` instance. Attaching to the global instance affects all requests made through `axios`, while attaching to a custom instance scopes the retry logic only to that instance.
fix
Use `rax.attach()` for global attachment. For scoped behavior, create an Axios instance (`const myAxios = axios.create();`) and then call `rax.attach(myAxios);`.
affects: >=3.0.0
breakingThe `retry-axios` configuration for an Axios instance is set via `myAxiosInstance.defaults.raxConfig`. Prior to v3, some configuration might have been set directly on the `axios` instance. Ensure you use the `raxConfig` property.
fix
Update your configuration to use the `raxConfig` property within `axios.defaults` or `axiosInstance.defaults`, e.g., `myAxiosInstance.defaults.raxConfig = {...};`.
affects: <3.0.0
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'attach')
Incorrect ESM import of the `retry-axios` library, often using a default import instead of a namespace import.
fix
Change `import rax from 'retry-axios';` to `import * as rax from 'retry-axios';`.
Error: ENODATA: no data: getaddrinfo EAI_AGAIN
Network error indicating a failure to resolve the hostname. While not directly caused by `retry-axios`, it's a common error that `retry-axios` is designed to handle.
fix
Ensure the target URL is correct and reachable. If it's an intermittent issue, `retry-axios` with its default configuration will attempt to retry, potentially resolving the issue on subsequent attempts. Check DNS settings and network connectivity.
ERR_BAD_RESPONSE: Request failed with status code 503
The server responded with a 5xx status code (e.g., Service Unavailable), which is typically a retryable error that `retry-axios` is configured to handle by default.
fix
This error itself is expected to be caught and retried by `retry-axios`. If retries are not happening, verify that `rax.attach()` was called and that `raxConfig.statusCodesToRetry` includes the relevant 5xx range. Increase `raxConfig.retry` if more attempts are needed.
Upgrade
Version history
4.0.3latest on npm
Audit
Dependencies
axiosrequiredPeer dependency as it integrates directly with Axios instances.
Agent activity
7 hits · last 30 days
node
6
Resources