# fetch-retry

> Extend any fetch library with retry functionality

Latest version **6.0.0** (published 2024-03-17) · MIT license · 0 weekly downloads

## Install

```sh
npm install fetch-retry
pnpm add fetch-retry
yarn add fetch-retry
bun add fetch-retry
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 6.0.0 |
| Published | 2024-03-17 |
| First published | 2016-03-27 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 53.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 318 |
| Author | Jon K. Bernhardsen |
| Maintainers | jonbern |
| Keywords | fetch, retry, http, retry, Fetch API |

## Links

- npm: https://www.npmjs.com/package/fetch-retry
- Repository: https://github.com/jonbern/fetch-retry
- Homepage: https://github.com/jonbern/fetch-retry#readme
- Issues: https://github.com/jonbern/fetch-retry/issues
- npm.io page: https://npm.io/package/fetch-retry

## Alternatives

- [launchdarkly-js-client-sdk](https://npm.io/package/launchdarkly-js-client-sdk.md) — 2.5M weekly downloads
- [@elastic/elasticsearch](https://npm.io/package/@elastic/elasticsearch.md) — 2.1M weekly downloads
- [@c8y/client](https://npm.io/package/@c8y/client.md) — 15.3K weekly downloads
- [@signaldb/maverickjs](https://npm.io/package/@signaldb/maverickjs.md) — 1.7K weekly downloads
- [@bbc/http-transport-cache](https://npm.io/package/@bbc/http-transport-cache.md) — 1.2K weekly downloads

## Recent versions

- 6.0.0 (latest) — 2024-03-17
- 5.0.6 — 2023-05-18
- 5.0.5 — 2023-05-03
- 5.0.4 — 2023-02-26
- 5.0.3 — 2022-07-01
- 5.0.2 — 2022-03-04
- 5.0.1 — 2021-09-14
- 5.0.0 — 2021-09-13
- 4.1.1 — 2021-04-03
- 4.1.0 — 2021-02-10
- 4.0.1 — 2020-07-02
- 4.0.0 — 2020-06-27
- 3.2.3 — 2020-06-22
- 3.2.2 — 2020-06-20
- 3.2.1 — 2020-06-20
- … 22 more at https://npm.io/package/fetch-retry/versions

## README

# fetch-retry

Adds retry functionality to the [Fetch](https://fetch.spec.whatwg.org/) API.

It wraps any `fetch` API package (eg: [isomorphic-fetch](https://github.com/matthew-andrews/isomorphic-fetch), [cross-fetch](https://github.com/lquixada/cross-fetch), [isomorphic-unfetch](https://github.com/developit/unfetch), or [Node.js native's fetch implementation](https://nodejs.org/dist/latest-v18.x/docs/api/globals.html#fetch)) and retries requests that fail due to network issues. It can also be configured to retry requests on specific HTTP status codes.

[![Node.js CI](https://github.com/jonbern/fetch-retry/actions/workflows/node.js.yml/badge.svg)](https://github.com/jonbern/fetch-retry/actions/workflows/node.js.yml)

## npm package

```javascript
npm install fetch-retry --save
```

## Example
`fetch-retry` is used the same way as `fetch`, but also accepts `retries`, `retryDelay`, and `retryOn` on the `options` object.

These properties are optional, and unless different defaults have been specified when requiring `fetch-retry`, these will default to 3 retries, with a 1000ms retry delay, and to only retry on network errors.

```javascript
const originalFetch = require('isomorphic-fetch');
const fetch = require('fetch-retry')(originalFetch);

// fetch-retry can also wrap Node.js's native fetch API implementation:
const fetch = require('fetch-retry')(global.fetch);
```

```javascript
fetch(url, {
    retries: 3,
    retryDelay: 1000
  })
  .then(function(response) {
    return response.json();
  })
  .then(function(json) {
    // do something with the result
    console.log(json);
  });
```

or passing your own defaults:

```javascript
const originalFetch = require('isomorphic-fetch');
const fetch = require('fetch-retry')(originalFetch, {
    retries: 5,
    retryDelay: 800
  });
```

> `fetch-retry` uses promises and requires you to polyfill the Promise API in order to support Internet Explorer.


## Example: Exponential backoff
The default behavior of `fetch-retry` is to wait a fixed amount of time between attempts, but it is also possible to customize this by passing a function as the `retryDelay` option. The function is supplied three arguments: `attempt` (starting at 0), `error` (in case of a network error), and `response`. It must return a number indicating the delay.

```javascript
fetch(url, {
    retryDelay: function(attempt, error, response) {
      return Math.pow(2, attempt) * 1000; // 1000, 2000, 4000
    }
  }).then(function(response) {
    return response.json();
  }).then(function(json) {
    // do something with the result
    console.log(json);
  });
```

## Example: Retry on 503 (Service Unavailable)
The default behavior of `fetch-retry` is to only retry requests on network related issues, but it is also possible to configure it to retry on specific HTTP status codes. This is done by using the `retryOn` property, which expects an array of HTTP status codes.

```javascript
fetch(url, {
    retryOn: [503]
  })
  .then(function(response) {
    return response.json();
  })
  .then(function(json) {
    // do something with the result
    console.log(json);
  });
```

## Example: Retry custom behavior
The `retryOn` option may also be specified as a function, in which case it will be supplied three arguments: `attempt` (starting at 0), `error` (in case of a network error), and `response`. Return a truthy value from this function in order to trigger a retry, any falsy value will result in the call to fetch either resolving (in case the last attempt resulted in a response), or rejecting (in case the last attempt resulted in an error).

```javascript
fetch(url, {
    retryOn: function(attempt, error, response) {
      // retry on any network error, or 4xx or 5xx status codes
      if (error !== null || response.status >= 400) {
        console.log(`retrying, attempt number ${attempt + 1}`);
        return true;
      }
    })
    .then(function(response) {
      return response.json();
    }).then(function(json) {
      // do something with the result
      console.log(json);
    });
```

## Example: Retry custom behavior with async
The `retryOn` option may also be used with async and await for calling asyncronous functions:

```javascript
fetch(url, {
    retryOn: async function(attempt, error, response) {
      if (attempt > 3) return false;

      if (error !== null) {
        var json = await response.json();
        if (json.property !== undefined) {
          return true;
        }
      }
    })
    .then(function(response) {
      return response.json();
    }).then(function(json) {
      // do something with the result
      console.log(json);
    });
```

---
_Source: https://npm.io/package/fetch-retry · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._