Production-grade Axios retry library for TypeScript and JavaScript — with concurrency control, request prioritization, automatic token refresh, response caching, circuit breaker, and composable plugins.

---

📖 Full Documentation · GitHub · npm · Changelog

---

What is axios-retryer?

axios-retryer is a drop-in Axios retry manager for Node.js, React, and any TypeScript or JavaScript project. It solves the hard parts that ad hoc retry interceptors get wrong: concurrent token refresh without duplicate calls, ordered request queues under backpressure, circuit breaking on unstable upstreams, response caching, and pluggable observability — all with zero magic and full type safety.

Key capabilities:

Feature	Description
🔄 Intelligent retries	Automatic or manual retry modes, exponential / linear / static backoff, fully custom strategies
🚦 Priority queue	CRITICAL → LOW priorities, binary-heap scheduling, configurable concurrency cap
🔑 Token refresh	Queues concurrent 401s, refreshes once, replays all requests with the new token
🛡️ Circuit breaker	Trips on N failures, fast-fails during recovery window, sliding-window analysis
💾 Response caching	TTR-based in-memory cache, exact / prefix / regex invalidation, swappable storage adapters
📊 Metrics & events	Live retry counters, timer health, rich lifecycle event hooks
🌳 Tree-shakeable plugins	Each plugin is a separate entry point — unused code is never bundled

Peer dependency: axios >= 1.7.4

---

Installation

npm install axios-retryer
# yarn add axios-retryer
# pnpm add axios-retryer

---

Quick Start

import { createRetryer } from 'axios-retryer';
import { createTokenRefreshPlugin } from 'axios-retryer/plugins/TokenRefreshPlugin';
import { createCircuitBreaker } from 'axios-retryer/plugins/CircuitBreakerPlugin';

// Chain .use() on one expression so TypeScript merges each plugin's event types
const retryer = createRetryer({
  retries: 3,
  maxConcurrentRequests: 10,
})
  .use(
    createTokenRefreshPlugin(async (axios) => {
      const { data } = await axios.post('/auth/refresh');
      return { token: data.accessToken };
    }),
  )
  .use(createCircuitBreaker({ failureThreshold: 5, openTimeout: 30_000 }));

// Drop-in replacement for your existing axios instance
const { data } = await retryer.axiosInstance.get('/api/users');

Try it: Interactive sandbox (browser, mocked HTTP)

---

Plugins

Import only what your application needs. Each plugin is independently tree-shakeable:

Plugin	Import path	Purpose
TokenRefreshPlugin	axios-retryer/plugins/TokenRefreshPlugin	Auth token refresh on 401; optional per-request opt-out
CircuitBreakerPlugin	axios-retryer/plugins/CircuitBreakerPlugin	Fail-fast on repeated upstream failures
CachingPlugin	axios-retryer/plugins/CachingPlugin	In-memory response cache with TTR invalidation
ManualRetryPlugin	axios-retryer/plugins/ManualRetryPlugin	Store failed requests and replay on reconnect
MetricsPlugin	axios-retryer/plugins/MetricsPlugin	Live retry counters and lifecycle events
DebugSanitizationPlugin	axios-retryer/plugins/DebugSanitizationPlugin	Redact secrets from debug logs

---

Behavior notes

• Retry-After header support. When a response carries a Retry-After header (numeric seconds or HTTP-date), it overrides the computed backoff delay for that retry. The honored value is capped at 5 minutes to prevent runaway waits.
• Backoff cap. All backoff strategies (static, linear, exponential) are capped at 60 seconds by default. Override via the maxBackoffDelayMs option on RetryManagerOptions.

---

How axios-retryer Compares

Feature	axios-retryer	axios-retry	retry-axios
Automatic & Manual retry modes	✅	❌	❌
Concurrency control	✅	❌	❌
Priority queue	✅	❌	❌
Token refresh (401 handling)	✅	❌	❌
Circuit breaker	✅	❌	❌
Response caching	✅	❌	❌
Request cancellation	✅	❌	❌
Plugin architecture	✅	❌	❌
TypeScript-first	✅	⚠️	⚠️
Tree-shakeable	✅	❌	❌

---

Performance

Benchmarks from the current release (standard profile, local suite):

• Healthy-path throughput (core scenario): 2,150 req/sec
• Peak burst throughput (stress scenario): 4,285 req/sec
• Cache hit rate: 100% (integration + hot-read scenarios)
• Test suite: 117 suites · 1414 tests (pnpm test:run); use pnpm test:quick for a faster local run (~75 suites, skips integration, performance, and package-contract)

See BENCHMARK_RESULTS.md for full methodology and raw numbers.

---

Documentation

Full API reference, all plugin options, guides, and migration notes:

https://samplexbro.github.io/axios-retryer

• Installation guide
• Configuration reference
• Plugins overview
• Production setup guide
• Offline support guide
• Migration: v1.x → v2.0
• API reference
• SECURITY.md · KNOWN_ISSUES.md · BENCHMARK_RESULTS.md

---

Contributing

Bug reports, feature ideas, and pull requests are welcome. See CONTRIBUTING.md for guidelines.

License

MIT — see LICENSE.

---

Made with ❤️ by sampleX (Serhii Zhabskyi)