Undici ships with a set of built-in interceptors that can be composed via\ndispatcher.compose() to add cross-cutting behaviour such as automatic\nretries, response decompression, redirect following, DNS caching, and more.
import { Agent, interceptors } from 'undici'\n\nconst { retry, redirect, decompress, dump, responseError, dns, cache, deduplicate } = interceptors\n\nconst agent = new Agent().compose([\n retry({ maxRetries: 3 }),\n redirect({ maxRedirections: 5 }),\n decompress()\n])\n\nconst response = await agent.request({ origin: 'https://example.com', path: '/', method: 'GET' })\nYou can also apply interceptors to a single Client or Pool:
import { Client, interceptors } from 'undici'\n\nconst client = new Client('https://example.com').compose(\n interceptors.retry({ maxRetries: 2 })\n)\nInterceptors are applied in the order they appear in the compose() call.\nThe first interceptor in the array wraps the outermost layer.
import { Agent, interceptors } from 'undici'\n\nconst agent = new Agent().compose([\n interceptors.dns({ maxTTL: 30_000 }),\n interceptors.retry({ maxRetries: 3 }),\n interceptors.redirect({ maxRedirections: 5 }),\n interceptors.decompress(),\n interceptors.responseError()\n])\nIn the example above the request flow is:
\nReads and discards the response body up to a configurable size limit. Useful\nfor keeping a connection alive after an error response without reading the\nbody yourself.
\nParameters
\nPer-request override: set dumpMaxSize on the dispatch options to override\nthe global maxSize for a specific request.
Returns: <Dispatcher.DispatcherComposeInterceptor>
Example
\nimport { Agent, interceptors } from 'undici'\n\nconst agent = new Agent().compose(\n interceptors.dump({ maxSize: 128 * 1024 }) // discard up to 128 KiB\n)\nAutomatically retries failed requests using the same options accepted by\nRetryHandler.
Parameters
\nReturns: <Dispatcher.DispatcherComposeInterceptor>
Example
\nimport { Agent, interceptors } from 'undici'\n\nconst agent = new Agent().compose(\n interceptors.retry({\n maxRetries: 5,\n minTimeout: 200,\n maxTimeout: 5000,\n timeoutFactor: 2,\n statusCodes: [429, 502, 503, 504]\n })\n)\nFollows HTTP redirects (3xx responses) automatically.
\nParameters
\nPer-request override: any of the four options above can also be set directly\non the dispatch options to override the interceptor defaults for a specific\nrequest.
\nReturns: <Dispatcher.DispatcherComposeInterceptor>
Example
\nimport { Agent, interceptors } from 'undici'\n\nconst agent = new Agent().compose(\n interceptors.redirect({\n maxRedirections: 10,\n throwOnMaxRedirect: true,\n stripHeadersOnCrossOriginRedirect: ['authorization', 'cookie']\n })\n)\nAutomatically decompresses response bodies encoded with gzip, x-gzip,\nbr (Brotli), deflate, compress, x-compress, or zstd.
\n\nExperimental: This interceptor is experimental and subject to change.\nA one-time
\nExperimentalWarningis emitted on first use.
Parameters
\nReturns: <Dispatcher.DispatcherComposeInterceptor>
Example
\nimport { Agent, interceptors } from 'undici'\n\nconst agent = new Agent().compose(\n interceptors.decompress({\n skipStatusCodes: [204, 304],\n skipErrorResponses: false // decompress error bodies too\n })\n)\nConverts 4xx/5xx responses into thrown ResponseError instances, making it\neasy to handle HTTP errors with a standard try/catch block.
The error body is automatically decoded for application/json and\ntext/plain responses. For JSON responses the body is parsed and exposed as\nerror.body.
Parameters
\nReturns: <Dispatcher.DispatcherComposeInterceptor>
Example
\nimport { Agent, interceptors, errors } from 'undici'\n\nconst agent = new Agent().compose(interceptors.responseError())\n\ntry {\n await agent.request({ origin: 'https://example.com', path: '/not-found', method: 'GET' })\n} catch (err) {\n if (err instanceof errors.ResponseError) {\n console.error(err.status, err.body)\n }\n}\nCaches DNS lookups so that repeated requests to the same origin reuse the\nresolved IP address instead of performing a fresh lookup every time. Supports\ndual-stack (IPv4 + IPv6) and custom lookup/storage implementations.
\nParameters
\nDNSStorage interface
interface DNSStorage {\n size: number\n get(origin: string): DNSInterceptorOriginRecords | null\n set(origin: string, records: DNSInterceptorOriginRecords | null, options: { ttl: number }): void\n delete(origin: string): void\n full(): boolean\n}\nReturns: <Dispatcher.DispatcherComposeInterceptor>
Example
\nimport { Agent, interceptors } from 'undici'\n\nconst agent = new Agent().compose(\n interceptors.dns({\n maxTTL: 60_000, // cache for at most 60 seconds\n dualStack: true,\n affinity: 4 // prefer IPv4\n })\n)\nCaches HTTP responses according to RFC 9111 (HTTP Caching). See\nCacheStore for information on providing a custom\nbacking store.
Parameters
\nReturns: <Dispatcher.DispatcherComposeInterceptor>
Example
\nimport { Agent, interceptors, cacheStores } from 'undici'\n\nconst agent = new Agent().compose(\n interceptors.cache({ store: new cacheStores.MemoryCacheStore() })\n)\nDeduplicates concurrent identical requests so that only one is sent over the\nwire. All waiting callers receive the same response once the in-flight request\ncompletes. Only safe HTTP methods (e.g. GET, HEAD) may be deduplicated.
Parameters
\nReturns: <Dispatcher.DispatcherComposeInterceptor>
Example
\nimport { Agent, interceptors } from 'undici'\n\nconst agent = new Agent().compose(\n interceptors.deduplicate({\n methods: ['GET', 'HEAD'],\n excludeHeaderNames: ['x-request-id', 'x-trace-id'],\n maxBufferSize: 2 * 1024 * 1024\n })\n)\n