{"id":16198,"library":"retry-axios","title":"Axios Request Retries","description":"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.","status":"active","version":"4.0.3","language":"javascript","source_language":"en","source_url":"https://github.com/JustinBeckwith/retry-axios","tags":["javascript","axios","retry","typescript"],"install":[{"cmd":"npm install retry-axios","lang":"bash","label":"npm"},{"cmd":"yarn add retry-axios","lang":"bash","label":"yarn"},{"cmd":"pnpm add retry-axios","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency as it integrates directly with Axios instances.","package":"axios","optional":false}],"imports":[{"note":"The library exports a namespace object `rax`. Direct default imports are incorrect and will lead to undefined behavior.","wrong":"import rax from 'retry-axios';","symbol":"rax","correct":"import * as rax from 'retry-axios';"},{"note":"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.","wrong":"import rax, { attach } from 'retry-axios';","symbol":"attach","correct":"import { attach } from 'retry-axios';"},{"note":"For CommonJS environments, `require('retry-axios')` correctly loads the module. Since v4.0.2, specific declarations were added for nodenext cjs consumers.","symbol":"rax (CommonJS)","correct":"const rax = require('retry-axios');"},{"note":"When using TypeScript, type definitions for Axios requests are extended with `RaxConfig`. Ensure both Axios and retry-axios types are available in your project.","symbol":"AxiosRequestConfig (Type)","correct":"import { AxiosRequestConfig } from 'axios';\nimport { RaxConfig } from 'retry-axios';"}],"quickstart":{"code":"import * as rax from 'retry-axios';\nimport axios, { AxiosInstance } from 'axios';\n\ninterface MyRaxConfig extends rax.RaxConfig {\n  // Optionally extend raxConfig if needed\n}\n\nconst myAxiosInstance: AxiosInstance = axios.create();\n\n// Configure retry-axios for this specific instance\nmyAxiosInstance.defaults.raxConfig = {\n  retry: 5, // Retry 5 times\n  retryDelay: 500, // 500ms delay between retries\n  statusCodesToRetry: [[429, 429], [500, 599]], // Only retry for Too Many Requests and 5xx errors\n  backoffType: 'exponential', // Use exponential backoff\n  jitter: 'full', // Add full jitter\n  onError: (err) => {\n    const cfg = rax.getConfig(err);\n    if (cfg) {\n      console.log(`Retry attempt #${cfg.currentRetryAttempt + 1} for URL: ${err.config?.url}`);\n    }\n  }\n} as MyRaxConfig;\n\n// Attach the retry interceptor to the custom instance\nrax.attach(myAxiosInstance);\n\nasync function fetchData() {\n  try {\n    // Simulate an API call that might fail and need retries\n    // Using httpbin.org for demonstration purposes.\n    // In a real scenario, this might be a flaky backend endpoint.\n    const response = await myAxiosInstance.get('https://httpbin.org/status/503');\n    console.log('Successfully fetched data:', response.data);\n  } catch (error: any) {\n    if (error.response) {\n      console.error(`Failed to fetch data after retries. Status: ${error.response.status}`);\n    } else if (error.request) {\n      console.error('Failed to fetch data after retries. No response received.');\n    } else {\n      console.error('Error during request setup:', error.message);\n    }\n  }\n}\n\nfetchData();","lang":"typescript","description":"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."},"warnings":[{"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.","message":"Version 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.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Always use `import * as rax from 'retry-axios';` for ESM imports. For CommonJS, `const rax = require('retry-axios');` is correct.","message":"When 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.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Use `rax.attach()` for global attachment. For scoped behavior, create an Axios instance (`const myAxios = axios.create();`) and then call `rax.attach(myAxios);`.","message":"`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.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Update your configuration to use the `raxConfig` property within `axios.defaults` or `axiosInstance.defaults`, e.g., `myAxiosInstance.defaults.raxConfig = {...};`.","message":"The `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.","severity":"breaking","affected_versions":"<3.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Change `import rax from 'retry-axios';` to `import * as rax from 'retry-axios';`.","cause":"Incorrect ESM import of the `retry-axios` library, often using a default import instead of a namespace import.","error":"TypeError: Cannot read properties of undefined (reading 'attach')"},{"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.","cause":"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.","error":"Error: ENODATA: no data: getaddrinfo EAI_AGAIN"},{"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.","cause":"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.","error":"ERR_BAD_RESPONSE: Request failed with status code 503"}],"ecosystem":"npm"}