axios-retry

axios-retry is a lightweight plugin that hooks into Axios’s interceptor chain to automatically retry failed HTTP requests, handling transient network errors and 5xx server responses without requiring extra application code at every call site.

Maintained by Softonic, it exposes configurable retry conditions, multiple delay strategies (no-delay, linear, exponential backoff with jitter), Retry-After header support, and per-request overrides, and is downloaded over 9 million times a week across the npm ecosystem.

What You Get

• Automatic retry interceptors that plug into any Axios instance or the global axios object
• Built-in retry condition helpers for network errors, safe methods, and idempotent methods
• Exponential backoff and linear delay strategies with jitter, plus support for a fully custom delay function
• Retry-After header support that respects server-specified backoff windows
• Per-request retry overrides via the axios-retry request config key

Common Use Cases

• Automatically retrying failed GET requests against unreliable third-party APIs
• Backing off exponentially when a backend service returns 5xx errors under load
• Respecting Retry-After headers when calling rate-limited REST APIs
• Refreshing auth tokens and retrying the original request on 401 responses

Under The Hood

Architecture The library is a single-file module (src/index.ts, ~340 lines) built around a functional/closure design: axiosRetry() registers a request and response interceptor pair via axiosInstance.interceptors, tracking per-request state by stashing a currentState object on config['axios-retry'], threading retryCount/lastRequestTime through Axios’s own config-merging behavior rather than an external store or class hierarchy. Retry decision (shouldRetry), retry execution (handleRetry), and max-retry escalation (handleMaxRetryTimesExceeded) are separated into focused async functions; delay strategies and retry-condition predicates are exported as free functions so callers can compose custom behavior without touching the core interceptor logic. The entire public surface is a single default-exported function with static properties attached for CommonJS interop. The core abstraction is the per-request state object threaded through Axios’s config object, which means the library is tightly coupled to that one specific Axios internal behavior continuing to hold.

Tech Stack Written in TypeScript, targeting dual ESM/CJS output via two tsconfig variants, built through raw tsc (no bundler) into dist/esm and dist/cjs with hand-written package.json stubs marking module type. The only runtime dependency is is-retry-allowed, used to filter out non-retryable errno codes; Axios itself is a peer dependency rather than a hard dependency, so consumers bring their own Axios version. Dev tooling includes ESLint plus typescript-eslint and Prettier for style, Husky and lint-staged for pre-commit gating, and ts-node running a Jasmine test suite against nock-mocked HTTP responses, with a single GitHub Actions workflow for CI.

Code Quality The test suite is a single, dense Jasmine spec file using nock to mock HTTP responses, with comprehensive coverage of retry conditions, delay functions, Retry-After handling, timeout interaction, and abort-signal behavior. Error handling favors typed AxiosError throughout, with explicit optional chaining rather than silent failure; the one broad catch deliberately falls back to a safe default for compatibility, and this is documented inline. Naming is consistent and intention-revealing, type safety is strong with dedicated interfaces plus module augmentation of Axios’s own config type, and linting/formatting is enforced both locally via pre-commit hooks and in CI.

API Design The public API is a single function call with zero required configuration, so the default case is a one-liner while advanced users can import the individual delay functions and condition predicates to compose custom retry behavior without forking the library. The README documents every option in one table with runnable examples for each delay strategy, and TypeScript types augment Axios’s own request config so editors surface autocomplete on the retry config key without extra work from the consumer.