Retry Plugin

The official retry plugin for endpoint-fetcher. Automatically retries failed requests with configurable backoff strategies.

GitHub · NPM

Installation


npm install @endpoint-fetcher/retry


pnpm add @endpoint-fetcher/retry


yarn add @endpoint-fetcher/retry


bun add @endpoint-fetcher/retry

Requires endpoint-fetcher v3.0.0 or higher.

Quick Start


import { createApiClient, get } from 'endpoint-fetcher';
import { retryPlugin } from '@endpoint-fetcher/retry';
 
const api = createApiClient({
  getUser: get<{ id: string }, User>((input) => `/users/${input.id}`),
}, {
  baseUrl: 'https://api.example.com',
  plugins: [
    retryPlugin({
      maxRetries: 3,
      strategy: 'exponential',
      baseDelay: 1000,
    }),
  ],
});
 
// Automatically retried on 5xx or network errors
const user = await api.getUser({ id: '123' });

Configuration

Option	Type	Default	Description
`maxRetries`	`number`	`3`	Maximum number of retry attempts
`strategy`	`'fixed' \| 'linear' \| 'exponential'`	`'exponential'`	Delay strategy between retries
`baseDelay`	`number`	`1000`	Base delay in milliseconds
`maxDelay`	`number`	`30000`	Maximum delay cap in milliseconds
`retryStatusCodes`	`number[]`	`[500, 502, 503, 504, 429]`	Status codes that trigger a retry
`retryMethods`	`string[]`	All methods	HTTP methods eligible for retry
`shouldRetry`	`(error, attempt) => boolean`	Checks `retryStatusCodes`	Custom retry condition
`onRetry`	`(error, attempt, delay) => void`	`() => {}`	Callback on each retry attempt

Retry Strategies

Strategy	Pattern	Formula
`fixed`	1s, 1s, 1s	`baseDelay`
`linear`	1s, 2s, 3s	`baseDelay × attempt`
`exponential`	1s, 2s, 4s, 8s	`baseDelay × 2^(attempt-1)`

All strategies are capped at maxDelay.

Default Retry Behavior

Retries on: 500, 502, 503, 504 (server errors), 429 (rate limiting), and network errors (no status code).

Does not retry: 4xx client errors (except 429), 2xx successful responses.

Advanced Usage

Custom Retry Condition


retryPlugin({
  maxRetries: 3,
  shouldRetry: (error, attempt) => {
    const err = error as { status?: number };
    if (!err.status) return true;         // Always retry network errors
    if (err.status === 429) return true;  // Retry rate limiting
    if (err.status === 408) return true;  // Retry request timeout
    return err.status >= 500;             // Retry server errors
  },
})

Monitoring Retries


retryPlugin({
  maxRetries: 3,
  onRetry: (error, attempt, delay) => {
    const err = error as { status?: number };
    console.warn(`Retry ${attempt} after ${delay}ms (status: ${err.status ?? 'network error'})`);
  },
})

Only Retry Idempotent Methods


retryPlugin({
  maxRetries: 3,
  retryMethods: ['GET', 'PUT', 'DELETE'], // skip POST
})

Combining with Cache


plugins: [
  retryPlugin({ maxRetries: 3, strategy: 'exponential' }),
  cache({ ttl: 300 }),
]

Execution order: the cache plugin checks first; on a cache miss, the retry plugin handles the request.

Troubleshooting

Requests are never retried — Check that maxRetries > 0, the status code is in retryStatusCodes, and the HTTP method is in retryMethods.

Too many retries causing performance issues — Reduce maxRetries, increase baseDelay, or set maxDelay. Use exponential strategy to naturally slow down.

Retries happening on client errors — Remove 4xx codes from retryStatusCodes, or use a custom shouldRetry that excludes them.