Configuration

All options passed to createRetryer() or the RetryManager constructor. Every option is optional and ships with a sensible default.

Full options reference

import {
  createRetryer,
  RETRY_MODES,
  AXIOS_RETRYER_BACKOFF_TYPES,
  AXIOS_RETRYER_HTTP_METHODS,
  AXIOS_RETRYER_REQUEST_PRIORITIES,
} from 'axios-retryer';

const retryer = createRetryer({
  // ── Retry behaviour ─────────────────────────────────────────────
  mode: RETRY_MODES.AUTOMATIC,            // AUTOMATIC | MANUAL (default: AUTOMATIC)
  retries: 3,                             // Max retry attempts per request (default: 3)

  // ── Backoff ─────────────────────────────────────────────────────
  backoffType: AXIOS_RETRYER_BACKOFF_TYPES.EXPONENTIAL,
  // STATIC | LINEAR | EXPONENTIAL (default: EXPONENTIAL)

  // ── What to retry ───────────────────────────────────────────────
  retryableStatuses: [408, 429, [500, 599] as const], // Status codes / ranges to retry
  retryableMethods: [                     // HTTP methods to retry (default: GET, HEAD, OPTIONS)
    AXIOS_RETRYER_HTTP_METHODS.GET,
    AXIOS_RETRYER_HTTP_METHODS.PUT,
  ],

  // ── Concurrency ─────────────────────────────────────────────────
  maxConcurrentRequests: 5,               // Parallel request cap (default: 5)
  queueDelay: 100,                        // ms between dequeuing (default: 100)
  maxQueueSize: 100,                      // Max queued requests; excess throws QueueFullError

  // ── Priority-based blocking ────────────────────────────────────────
  blockingPriorityThreshold: AXIOS_RETRYER_REQUEST_PRIORITIES.CRITICAL,
  // Requests at or above this priority block lower-priority work in the queue
  cancelPendingOnDependencyFailure: true, // Cancel queued requests if a blocker fails (default: true)

  // ── Error handling ──────────────────────────────────────────────
  throwErrorOnFailedRetries: true,        // Throw after all retries fail (default: true)
  throwErrorOnCancelRequest: true,        // Throw on cancellation (default: true)

  // ── Bring your own Axios instance ────────────────────────────────
  axiosInstance: myBaseAxios,             // Existing axios instance to wrap

  // ── Custom retry strategy ────────────────────────────────────────
  retryStrategy: myCustomStrategy,        // IRetryStrategy implementation

  // ── Logging ─────────────────────────────────────────────────────
  debug: false,                           // Verbose internal logs (default: false)
  logger: myLogger,                       // Custom logger (default: console-based)
});

Retry modes

Mode	Behavior	When to use
`RETRY_MODES.AUTOMATIC`	Retries transparently on failure	Most apps — transient failures handled for you
`RETRY_MODES.MANUAL`	Fails on first attempt; no automatic retry	Add `ManualRetryPlugin` when you want stored replay

Backoff types

Type	Delay formula	Example delays (attempts 1–3)
`STATIC`	constant	1s, 1s, 1s
`LINEAR`	attempt × base	1s, 2s, 3s
`EXPONENTIAL`	base × 2^attempt	1s, 2s, 4s

Request-level overrides

Pass __axiosRetryer in the Axios request config to override behaviour per request:

import { AXIOS_RETRYER_REQUEST_PRIORITIES, AXIOS_RETRYER_BACKOFF_TYPES } from 'axios-retryer';

retryer.axiosInstance.get('/api/data', {
  __axiosRetryer: {
    priority: AXIOS_RETRYER_REQUEST_PRIORITIES.HIGH,   // Queue priority
    requestId: 'fetch-data',                           // Stable ID for cancellation
    retries: 5,                                        // Override global retry count
    backoffType: AXIOS_RETRYER_BACKOFF_TYPES.LINEAR,   // Override backoff
    retryableStatuses: [503],                          // Override retryable statuses
  },
});

Custom retry strategy

import { createRetryStrategy, createRetryer } from 'axios-retryer';

const strategy = createRetryStrategy({
  isRetryable: (error) =>
    !error.response || (error.response.status >= 500 && error.response.status < 600),

  shouldRetry: (error, attempt, maxRetries) => {
    if (error.config?.method?.toLowerCase() === 'post' && attempt >= 1) return false;
    return attempt <= maxRetries;
  },

  getDelay: (attempt) => {
    const base = attempt * 1000;
    const jitter = Math.random() * 500;
    return base + jitter;       // Linear with jitter
  },
});

const retryer = createRetryer({ retryStrategy: strategy });

Custom logger

const retryer = createRetryer({
  debug: true,
  logger: {
    log: (msg) => myMonitoring.info(msg),
    warn: (msg) => myMonitoring.warn(msg),
    error: (msg) => myMonitoring.error(msg),
  },
});

Retry Modes →