HTTP(S) Request Retry

Common errors

• Error: Cannot find module 'postman-request'

  cause The peer dependency 'postman-request' is not installed in the project.
  fix Run `npm install postman-request` to install the required HTTP client.

• TypeError: request is not a function

  cause Attempting to use `requestretry` with an ES module `import` statement in a CommonJS-only Node.js environment, or an incorrect import style.
  fix Use CommonJS `require` syntax: `const request = require('requestretry');` Ensure your project's module type is correctly configured if using ESM.

• (node:xyz) DeprecationWarning: The request package has been deprecated.

  cause This warning indicates that your project (or a transitive dependency) is still using an older version of `request-retry` (pre-v8.0.0) which relies on the deprecated `request` library.
  fix Upgrade `request-retry` to version 8.0.0 or higher: `npm install requestretry@latest`. Also, ensure `postman-request` is installed as a peer dependency.

Warnings

• breaking Version 8.0.0 replaced the deprecated `request` library with `postman-request`. This is a breaking change in its underlying dependency, though the API surface aims to remain compatible. Users must explicitly install `postman-request` as a peer dependency.
  Fix: Ensure `postman-request` is installed in your project: `npm install postman-request`
• gotcha The original `request` library, on which older versions of `request-retry` were based, is deprecated and no longer maintained. While v8.0.0 migrates to `postman-request`, users should be aware that `postman-request` is a fork and may have subtle differences or its own future maintenance considerations.
  Fix: For new projects, consider modern alternatives to the `request` API if deep integration or long-term stability with the underlying HTTP client is critical, or rely on `postman-request`'s continued maintenance.
• gotcha `request-retry` expects `postman-request` as a peer dependency. If `postman-request` is not installed, the library will fail with a module not found error, as it cannot function without its underlying HTTP client.
  Fix: Install the peer dependency: `npm install postman-request`.

Install

• npm install requestretry npm
• yarn add requestretry yarn
• pnpm add requestretry pnpm

Imports

• request
  wrong:

  import request from 'requestretry';

  correct:

  const request = require('requestretry');

  Primarily designed for CommonJS. For ESM, direct `import` requires a build step or Node.js's CJS interoperability.
• RetryStrategies
  wrong:

  import { RetryStrategies } from 'requestretry';

  correct:

  const request = require('requestretry');
  const strategy = request.RetryStrategies.HTTPOrNetworkError;

  RetryStrategies is an enumerable property on the main 'requestretry' export, not a separate named export.
• request (Promise-based usage)
  wrong:

  import requestPromise from 'requestretry/promise';

  correct:

  const request = require('requestretry');
  request({ /* options */ }).then(/* ... */);

  Promise support is built into the main 'requestretry' export; no separate promise-specific import is needed.

Quickstart

Demonstrates a basic promise-based HTTP GET request using request-retry, configured to retry on 5xx errors or network issues with a delay.

// First, ensure you have the necessary peer dependency installed:
// npm install requestretry postman-request

const request = require('requestretry');

async function makeRetriedRequest() {
  console.log('Initiating retriable HTTP request...');
  try {
    const response = await request({
      url: 'https://httpstat.us/503', // An endpoint that reliably returns a 503 (Service Unavailable)
      json: true, // Parse response body as JSON
      maxAttempts: 3,   // Configure up to 3 attempts
      retryDelay: 1000,  // Wait 1 second between retries
      retryStrategy: request.RetryStrategies.HTTPOrNetworkError, // Retry on 5xx status codes or network errors
      fullResponse: true // Resolve the promise with the full response object, including headers and status
    });

    console.log(`\nRequest successfully completed after ${response.attempts} attempts.`);
    console.log(`HTTP Status Code: ${response.statusCode}`);
    console.log(`Response Body: ${JSON.stringify(response.body, null, 2)}`);
  } catch (error) {
    console.error(`\nRequest failed after all attempts. Error: ${error.message}`);
    if (error.attempts) {
      console.error(`Total attempts made: ${error.attempts}`);
    }
  }
}

makeRetriedRequest();