A Dispatcher handler that automatically retries a request when it fails\nwith a recoverable network error or an eligible HTTP status code. It wraps an\ninner handler and re-dispatches the request, applying an exponential backoff and\nhonouring the Retry-After response header. When a response is partially\nconsumed before the failure, the handler resumes the download with a Range\nrequest guarded by the original ETag.
The handler is most often used indirectly through RetryAgent, but it can\nalso be supplied directly to dispatcher.dispatch() for fine-grained\ncontrol over the retry behaviour.
import { RetryHandler } from 'undici'\n<DispatchHandler>Implements the DispatchHandler interface. An instance is consumed by a\nsingle dispatch call and forwards the dispatch lifecycle to the inner handler,\nre-issuing the request through the supplied dispatch function whenever a retry\nis warranted.
\n", "signatures": [ { "textRaw": "`new RetryHandler(options, retryHandlers)`", "name": "RetryHandler", "type": "ctor", "meta": { "added": [ "v5.28.0" ], "changes": [ { "version": "v7.0.0", "pr-url": "https://github.com/nodejs/undici/pull/3883", "description": "Reimplemented on top of the new dispatch lifecycle hooks." } ] }, "params": [ { "textRaw": "`options` {DispatchOptions} The dispatch options for the request, extended with an optional `retryOptions` field. Type is `DispatchOptions & { retryOptions?: RetryOptions }`.", "name": "options", "type": "DispatchOptions", "desc": "The dispatch options for the request, extended with an optional `retryOptions` field. Type is `DispatchOptions & { retryOptions?: RetryOptions }`.", "options": [ { "textRaw": "`retryOptions` {RetryOptions} (optional) Configuration controlling when and how the request is retried. See `RetryOptions`.", "name": "retryOptions", "type": "RetryOptions", "desc": "(optional) Configuration controlling when and how the request is retried. See `RetryOptions`." } ] }, { "textRaw": "`retryHandlers` {RetryHandlers} The handlers used to drive the retry loop. See `RetryHandlers`.", "name": "retryHandlers", "type": "RetryHandlers", "desc": "The handlers used to drive the retry loop. See `RetryHandlers`." } ], "return": { "textRaw": "Returns: {RetryHandler}", "name": "return", "type": "RetryHandler" }, "modules": [ { "textRaw": "`RetryOptions`", "name": "`retryoptions`", "type": "module", "desc": "Note: The
\nRetryHandlerdoes not retry over stateful bodies (for example\nstreams orAsyncIterable), because once consumed they cannot be replayed. In\nthese situations the body is identified as stateful and the request is rejected\nwith theUND_ERR_REQ_RETRYerror instead of being retried.
throwOnError <boolean> When true, an error is thrown on the last retry\nattempt and propagated to the inner handler; when false, the failing response\nis passed through instead, which is useful when the error body is needed or a\ncustom error handler is in place. Default: true.retry <Function> Callback invoked on every retry iteration to decide whether\nanother attempt should be made. It receives the error, the retry context, and a\ncallback. Call the callback with an Error to stop retrying, or with null to\nschedule another attempt. Default: the built-in retry strategy described\nbelow.\nerr <Error> The error that triggered the retry.context <RetryContext> The current retry context. See RetryContext.callback <Function> Signals the outcome of this iteration.\n\nmaxRetries <number> Maximum number of retries allowed. Default: 5.maxTimeout <number> Maximum number of milliseconds to wait between retries. Default: 30000 (30 seconds).minTimeout <number> Initial number of milliseconds to wait before the first\nretry. Default: 500 (half a second).timeoutFactor <number> Multiplier applied to the timeout between successive\nretries to produce an exponential backoff. Default: 2.retryAfter <boolean> When true, the delay before the next retry is inferred\nfrom the Retry-After response header when present. Default: true.methods <string>[] HTTP methods that are eligible for retrying. Default:\n['GET', 'HEAD', 'OPTIONS', 'PUT', 'DELETE', 'TRACE'].statusCodes <number>[] HTTP status codes that trigger a retry. Default:\n[500, 502, 503, 504, 429].errorCodes <string>[] Network error codes that trigger a retry. Default:\n['ECONNRESET', 'ECONNREFUSED', 'ENOTFOUND', 'ENETDOWN', 'ENETUNREACH', 'EHOSTDOWN', 'EHOSTUNREACH', 'EPIPE', 'UND_ERR_SOCKET'].The default retry strategy computes the delay before the next attempt as\nminTimeout * timeoutFactor ** (counter - 1), capped at maxTimeout. When a\nRetry-After header is present it takes precedence (interpreted as seconds, or as\nan HTTP date), still capped at maxTimeout. The default strategy stops retrying\nonce counter exceeds maxRetries, when the error code is not in errorCodes,\nwhen the method is not in methods, or when the response status code is not in\nstatusCodes.
state <RetryState> The current retry state. See RetryState.opts <DispatchOptions> The dispatch options passed to the handler, including\nthe resolved retryOptions. Type is\nDispatchOptions & { retryOptions?: RetryOptions }.The context object passed as the second argument to the retry callback.
counter <number> The current retry attempt, starting at 1 for the first\nretry.Represents the retry state for a given request.
", "displayName": "`RetryState`" }, { "textRaw": "Parameter: `RetryHandlers`", "name": "parameter:_`retryhandlers`", "type": "module", "desc": "dispatch <Function> The dispatch function called to (re-)issue the request on\nevery attempt. Type is (options, handler) => boolean.handler <DispatchHandler> The inner handler invoked once the request succeeds\nor the retries are exhausted.import { Client, RetryHandler } from 'undici'\n\nconst client = new Client(`http://localhost:${server.address().port}`)\nconst chunks = []\n\nconst handler = new RetryHandler(\n {\n ...dispatchOptions,\n retryOptions: {\n // Custom retry decision function.\n retry (err, { state, opts }, callback) {\n if (err.code === 'UND_ERR_DESTROYED') {\n callback(err)\n return\n }\n\n if (err.statusCode === 206) {\n callback(err)\n return\n }\n\n setTimeout(() => callback(null), 1000)\n }\n }\n },\n {\n dispatch (...args) {\n return client.dispatch(...args)\n },\n handler: {\n onRequestStart () {},\n onResponseStart (controller, status, headers) {\n // Do something with the response headers.\n },\n onResponseData (controller, chunk) {\n chunks.push(chunk)\n },\n onResponseEnd () {},\n onResponseError (controller, err) {\n // Handle the error.\n }\n }\n }\n)\n\nclient.dispatch(dispatchOptions, handler)\nA minimal handler that relies entirely on the default retry options:
\nimport { Client, RetryHandler } from 'undici'\n\nconst client = new Client(`http://localhost:${server.address().port}`)\n\nconst handler = new RetryHandler(dispatchOptions, {\n dispatch: client.dispatch.bind(client),\n handler: {\n onRequestStart () {},\n onResponseStart (controller, status, headers) {},\n onResponseData (controller, chunk) {},\n onResponseEnd () {},\n onResponseError (controller, err) {}\n }\n})\n\nclient.dispatch(dispatchOptions, handler)\n