Registry / devops / fetch-with-retries

fetch-with-retries

library2.3.0jsnpmunverified

Simple and opinionated library that adds automatic retry logic to native Node.js `fetch` (available since Node 20). Current version 2.3.0. Release cadence is sporadic. Key differentiators: built-in exponential backoff, support for `Retry-After` and `X-RateLimit-Reset` headers, custom retry conditions, timeout option, and ability to abort wait between retries. Unlike more generic retry libraries (e.g., `retry`), this one is tightly focused on fetch and handles rate limiting headers natively.

devops

npm install fetch-with-retries

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · FETCH-WITH-RETRIES

fetch-with-retries

devopsjavascriptv2.3.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

fetchWithRetries

✓ import { fetchWithRetries } from 'fetch-with-retries'

✗ import fetchWithRetries from 'fetch-with-retries'

This is a named export, not a default export.

TimeoutError

✓ import { TimeoutError } from 'fetch-with-retries'

✗ import { TimeoutError } from 'fetch-with-retries/src/index'

TimeoutError is exported from the package root.

FetchOptionsWithRetries

✓ import type { FetchOptionsWithRetries } from 'fetch-with-retries'

✗ import { FetchOptionsWithRetries } from 'fetch-with-retries'

This is a TypeScript type, not a runtime value. In TypeScript, use `import type`.

require

✓ const { fetchWithRetries } = require('fetch-with-retries')

✗ const fetchWithRetries = require('fetch-with-retries')

CommonJS users must destructure the named export.

Shows basic usage: fetch with retries, handling TimeoutError, and logging retry attempts.

import { fetchWithRetries } from 'fetch-with-retries'; async function fetchData() { try { const response = await fetchWithRetries('https://api.example.com/data', { retries: 3, retryDelay: 1000, // initial delay in ms timeout: 5000, onRetry: (attempt, error) => { console.log(`Retry attempt ${attempt} due to:`, error); } }); const data = await response.json(); console.log(data); } catch (error) { if (error.name === 'TimeoutError') { console.error('Request timed out'); } else { console.error('Request failed after all retries:', error); } } } fetchData();

Debug

Known issues

gotchafetchWithRetries() requires native fetch, which is only available in Node >= 20.

fix

Either upgrade to Node >= 20 or use a polyfill like 'node-fetch' before calling fetchWithRetries.

affects: >=2.0.0

gotchaThe 'timeout' option does not abort the underlying fetch request properly; it only times out the overall operation.

fix

Upgrade to 2.1.0+ where timeout correctly uses AbortController to cancel the fetch.

affects: <2.1.0

gotchaCustom retry conditions via 'retryIf' may not work as expected if the predicate does not account for network errors.

fix

Ensure 'retryIf' also checks for 'error instanceof TypeError' to cover network failures.

affects: >=2.0.0

deprecatedThe 'maxRetryTime' option is deprecated in favor of 'timeout'.

fix

Use 'timeout' instead of 'maxRetryTime'.

affects: >=2.2.0

Errors

Common errors & fixes

TypeError: fetchWithRetries is not a function

Using default import instead of named import.

fix

Use: import { fetchWithRetries } from 'fetch-with-retries';

Error: fetch is not defined

Node version < 20 where native fetch is not available.

fix

Upgrade Node to >= 20 or use a polyfill like node-fetch.

Error: TimeoutError is not defined

Trying to catch TimeoutError without importing it.

fix

Add: import { TimeoutError } from 'fetch-with-retries';

Upgrade

Version history

2.3.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/francescorivola/fetch-with-retries ↗

packagefetch-with-retries ↗

homepagehttps://github.com/francescorivola/fetch-with-retries ↗