Axios Request Retries

Common errors

• TypeError: Cannot read properties of undefined (reading 'attach')

  cause 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

  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.
  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

  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.
  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.

Warnings

• breaking 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.
  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.
• gotcha 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.
  Fix: Always use `import * as rax from 'retry-axios';` for ESM imports. For CommonJS, `const rax = require('retry-axios');` is correct.
• 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);`.
• breaking 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.
  Fix: Update your configuration to use the `raxConfig` property within `axios.defaults` or `axiosInstance.defaults`, e.g., `myAxiosInstance.defaults.raxConfig = {...};`.

Install

• npm install retry-axios npm
• yarn add retry-axios yarn
• pnpm add retry-axios pnpm

Imports

• rax
  wrong:

  import rax from 'retry-axios';

  correct:

  import * as rax from 'retry-axios';

  The library exports a namespace object `rax`. Direct default imports are incorrect and will lead to undefined behavior.
• attach
  wrong:

  import rax, { attach } from 'retry-axios';

  correct:

  import { 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.

Quickstart

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();