Reference for undici’s RetryHandler class — configure per-request retry with custom callbacks, exponential backoff, and fine-grained error code control.
Use this file to discover all available pages before exploring further.
RetryHandler is a handler class (not a dispatcher) that wraps another handler and re-dispatches a request on failure. Unlike the interceptors.retry interceptor, which applies retry logic globally to every request on a dispatcher, RetryHandler gives you request-level control: you construct it explicitly for a single dispatch() call, making it ideal when different endpoints within the same application require different retry policies.
options is an intersection of Dispatcher.DispatchOptions and RetryOptions. All standard dispatch options (path, method, headers, body, etc.) are passed through, and the retry configuration lives in the nested retryOptions key.
When true, the Retry-After response header is honoured. Both relative seconds and absolute date strings are supported. The value is still capped at maxTimeout.
When true, throws after all retries are exhausted. Set to false to receive the error response body without an exception — useful when the server’s error payload contains information your code needs.
Custom retry decision function. When provided, it completely replaces the default exponential backoff logic. Call callback(null) to schedule a retry or callback(err) to abort retrying. See Custom retry callback below.
The dispatch function to invoke on each retry attempt — typically client.dispatch.bind(client). This is called again with the same options (plus any Range headers if partial content was received) on each retry.
The downstream handler that receives events once the request ultimately succeeds or retries are exhausted. Must implement the standard dispatch handler interface (onRequestStart, onResponseStart, onResponseData, onResponseEnd, onResponseError).
When you provide a retry function in retryOptions, it is called after every failed attempt with three arguments:
retry( err: Error, // The error that caused the failure context: RetryContext, // Current retry state and options callback: (err?: Error | null) => void // Signal retry or abort): void
The full merged options passed to the RetryHandler constructor. Useful for reading the current method, headers, or retry configuration inside the callback.
Call callback(null) to proceed with the next retry (after whatever delay your logic imposes), or callback(err) to stop retrying and propagate err to the handler’s onResponseError.
interceptors.retry is implemented by creating a RetryHandler internally on every request, merging global interceptor options with per-request retryOptions.
RetryHandler is aware of partial responses. When a response with a known Content-Length or Content-Range is interrupted mid-stream, subsequent retry attempts add a Range: bytes=<offset>- header to resume from where the previous attempt left off. An If-Match header with the original ETag is included when available to detect resource changes between attempts.
Requests with stateful bodies — Readable streams or AsyncIterable instances that have already started emitting data — cannot be replayed. RetryHandler detects this and aborts with UND_ERR_REQ_RETRY rather than silently sending a truncated or incorrect body.