Registry / devops / http-fetch-retry

http-fetch-retry

library3.0.0jsnpmunverified

Lightweight Node.js library that extends native fetch with automatic retries, exponential backoff with jitter, and request timeout via AbortController. Version 3.0.0 requires Node.js >=22 and ships TypeScript types, ESM, and CJS. Unlike alternatives like node-fetch-retry or got, it returns a native Response object and does not throw on HTTP error statuses (4xx/5xx). It supports customizable retry strategies, strict validation mode, and detailed logging/warning/decision events. Published under MIT license with automated CI on Node 22, 24, and 26.

devops

npm install http-fetch-retry

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · HTTP-FETCH-RETRY

http-fetch-retry

devopsjavascriptv3.0.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.

HttpClient

✓ import { HttpClient } from 'http-fetch-retry'

✗ import { fetchWithRetry } from 'http-fetch-retry'

HttpClient is a class; fetchWithRetry is a static method. Import the class, not the method.

HttpClient (CommonJS)

✓ const { HttpClient } = require('http-fetch-retry')

✗ const httpFetchRetry = require('http-fetch-retry')

CommonJS destructures HttpClient from the module. Direct require returns the module object.

type imports

✓ import type { HttpClientOptions, RetryDecision, WarningEntry } from 'http-fetch-retry'

✗ import { HttpClientOptions } from 'http-fetch-retry'

TypeScript users should import types with `import type` to avoid runtime overhead.

Shows minimal usage: import HttpClient, call fetchWithRetry with a URL, check response.ok, and parse JSON.

import { HttpClient } from 'http-fetch-retry'; const response = await HttpClient.fetchWithRetry({ url: 'https://api.example.com/data', method: 'GET', }); if (!response.ok) { console.error('Request failed with status:', response.status); } else { const data = await response.json(); console.log('Data:', data); }

Debug

Known issues

breakingSince v3, fetchWithRetry returns a native Response and does NOT throw on HTTP error status codes (4xx/5xx).

fix

Check response.ok or response.status instead of catching errors for HTTP errors.

affects: >=3.0.0

deprecatedThe constructor HttpClient(options) is deprecated in v3; use HttpClient.fetchWithRetry() static method.

fix

Replace `new HttpClient(options).fetchWithRetry(...)` with `HttpClient.fetchWithRetry(..., options)`.

affects: >=3.0.0

gotchaWhen using strict mode, non-reusable body (e.g., ReadableStream) with retries enabled throws before sending.

fix

Ensure body is re-useable (string, Buffer, Blob, etc.) or disable retries for that request.

affects: >=3.0.0

gotchaIf you define retryMethods in strict mode, the array must not be empty, otherwise an error is thrown.

fix

Provide at least one HTTP method in retryMethods when strict is true.

affects: >=3.0.0

Errors

Common errors & fixes

TypeError: Failed to execute 'json' on 'Response': body stream already read

Response body consumed by previous retry attempt due to non-reusable body.

fix

Use a re-useable body (string, Buffer, Blob) or increase maxRetries only when body is re-useable.

Error: Cannot find module 'http-fetch-retry'

CommonJS require without ESM support; package does not support older Node.js <22.

fix

Upgrade Node.js to >=22 or use dynamic import().

TypeError: http_fetch_retry.HttpClient.fetchWithRetry is not a function

Incorrect import: default import instead of named import.

fix

Use `import { HttpClient } from 'http-fetch-retry'` (named import).

Upgrade

Version history

3.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/Skojen/http-fetch-retry ↗

packagehttp-fetch-retry ↗

homepagehttps://github.com/Skojen/http-fetch-retry#readme ↗