Class: HttpRetryPolicy

HttpRetryPolicy()

Configuration and logic for HTTP request retry policies.

Constructor

new HttpRetryPolicy()

Since:
  • 2.37.0
Source:
Example
const retryPolicy = new HttpRetryPolicy({
  maxRetries: 3,
  baseDelayMs: 500,
  retryOn: [500, 502, 503, 504],
  retryNetworkErrors: true,
});
retryPolicy.shouldRetry({
  attempt: 1,
  status: 500,
  isNetworkError: false,
});
// returns true

Members

maxAttempts

Maximum number of attempts including the initial request.
Source:

Methods

computeDelay(params) → {number}

Compute the delay before the next retry attempt using exponential backoff (double the delay after each failed attempt) and jitter.
Parameters:
Name Type Description
params object Parameters object.
Properties
Name Type Attributes Description
attempt number Current attempt number (1-based). Values <1 are treated as the first attempt.
retryAfterMs number | null <optional>
 Explicit delay that overrides backoff (e.g., already parsed from headers elsewhere) and takes precedence over the `Retry-After` header.
headers Headers | object | null <optional>
 Optional headers object to check for a `Retry-After` header. If present and valid, its value will be used as the delay and will override the exponential backoff calculation.
baseDelayMs number <optional>
 Optional base delay override for the backoff calculation.
maxDelayMs number | null <optional>
 Optional maximum delay cap; set to null to disable capping.
Source:
Returns:
Delay in milliseconds before the next retry attempt.
Type
number

parseRetryAfter(headers, maxDelayMsopt) → {number|null}

Parse a `Retry-After` header into a millisecond delay. Accepts either a Headers-like object with `.get()` or a plain object with a `Retry-After` property.
Parameters:
Name Type Attributes Description
headers Headers | object | null The headers returned from the server. Can be a `Headers` instance or a plain object. Null/undefined if no headers are available.
maxDelayMs number <optional>
 Override maximum delay cap in milliseconds.
Source:
Returns:
Millisecond delay or `null` when the header is missing or invalid.
Type
number | null

shouldRetry(params) → {boolean}

Decide whether a request should be retried based on attempt count, status code, and network errors.
Parameters:
Name Type Description
params object Parameters object.
Properties
Name Type Attributes Description
attempt number Current attempt number (1-based).
maxAttempts number <optional>
 Override the maximum attempts.
status number | string | null HTTP status code from the response (if any).
isNetworkError boolean Whether the last attempt failed due to a network issue.
Source:
Returns:
`true` when the request should be retried.
Type
boolean

shouldRetryStatus(status, retryOnopt) → {boolean}

Determine if a status code is configured as retryable.
Parameters:
Name Type Attributes Description
status number HTTP status code.
retryOn Array.<number> <optional>
 Override array of status codes to check.
Source:
Returns:
`true` when the status code should be retried.
Type
boolean

withOverrides(overrides) → {HttpRetryPolicy}

Create a new HttpRetryPolicy with some overridden options.
Parameters:
Name Type Description
overrides object Options to override. See constructor for details.
Source:
Returns:
New HttpRetryPolicy instance.
Type
HttpRetryPolicy

normalizeStatus(status) → {number|null}

Normalize a status code to a valid HTTP status code number. Converts strings to numbers. Returns `null` for invalid codes.
Parameters:
Name Type Description
status number | string HTTP status code.
Source:
Returns:
Normalized status code or `null` when invalid.
Type
number | null

HttpRetryPolicy(optionsopt)

new HttpRetryPolicy(optionsopt)

Parameters:
Name Type Attributes Description
options object <optional>
 Retry policy configuration.
Properties
Name Type Attributes Description
maxRetries number <optional>
 Number of retry attempts (excludes initial attempt).
baseDelayMs number <optional>
 Initial backoff delay in milliseconds.
maxDelayMs number <optional>
 Maximum backoff delay in milliseconds. Set to `null` to disable capping or 0 to retry immediately.
retryOn Array.<number> <optional>
 Status codes that should be retried.
retryNetworkErrors boolean <optional>
 Whether to retry network errors (such DNS failures or connection timeouts) when the status code is not available.
randomFn function <optional>
 Function used for jitter (useful for testing). Should return a number between 0 and 1.
Source:

Members

maxAttempts

Maximum number of attempts including the initial request.
Source:

Methods

computeDelay(params) → {number}

Compute the delay before the next retry attempt using exponential backoff (double the delay after each failed attempt) and jitter.
Parameters:
Name Type Description
params object Parameters object.
Properties
Name Type Attributes Description
attempt number Current attempt number (1-based). Values <1 are treated as the first attempt.
retryAfterMs number | null <optional>
 Explicit delay that overrides backoff (e.g., already parsed from headers elsewhere) and takes precedence over the `Retry-After` header.
headers Headers | object | null <optional>
 Optional headers object to check for a `Retry-After` header. If present and valid, its value will be used as the delay and will override the exponential backoff calculation.
baseDelayMs number <optional>
 Optional base delay override for the backoff calculation.
maxDelayMs number | null <optional>
 Optional maximum delay cap; set to null to disable capping.
Source:
Returns:
Delay in milliseconds before the next retry attempt.
Type
number

parseRetryAfter(headers, maxDelayMsopt) → {number|null}

Parse a `Retry-After` header into a millisecond delay. Accepts either a Headers-like object with `.get()` or a plain object with a `Retry-After` property.
Parameters:
Name Type Attributes Description
headers Headers | object | null The headers returned from the server. Can be a `Headers` instance or a plain object. Null/undefined if no headers are available.
maxDelayMs number <optional>
 Override maximum delay cap in milliseconds.
Source:
Returns:
Millisecond delay or `null` when the header is missing or invalid.
Type
number | null

shouldRetry(params) → {boolean}

Decide whether a request should be retried based on attempt count, status code, and network errors.
Parameters:
Name Type Description
params object Parameters object.
Properties
Name Type Attributes Description
attempt number Current attempt number (1-based).
maxAttempts number <optional>
 Override the maximum attempts.
status number | string | null HTTP status code from the response (if any).
isNetworkError boolean Whether the last attempt failed due to a network issue.
Source:
Returns:
`true` when the request should be retried.
Type
boolean

shouldRetryStatus(status, retryOnopt) → {boolean}

Determine if a status code is configured as retryable.
Parameters:
Name Type Attributes Description
status number HTTP status code.
retryOn Array.<number> <optional>
 Override array of status codes to check.
Source:
Returns:
`true` when the status code should be retried.
Type
boolean

withOverrides(overrides) → {HttpRetryPolicy}

Create a new HttpRetryPolicy with some overridden options.
Parameters:
Name Type Description
overrides object Options to override. See constructor for details.
Source:
Returns:
New HttpRetryPolicy instance.
Type
HttpRetryPolicy

normalizeStatus(status) → {number|null}

Normalize a status code to a valid HTTP status code number. Converts strings to numbers. Returns `null` for invalid codes.
Parameters:
Name Type Description
status number | string HTTP status code.
Source:
Returns:
Normalized status code or `null` when invalid.
Type
number | null