- Superior performance, especially with `undici.request`

- HTTP/1.1 pipelining support

- Custom interceptors and middleware

- Advanced features like `ProxyAgent`, `Socks5Agent`, `MockAgent`

**Cons:**

- Additional dependency to manage

- You need the latest undici features and performance improvements

- You require advanced connection pooling configuration

- You need APIs not available in the built-in fetch (`ProxyAgent`, `Socks5Agent`, `MockAgent`, etc.)

- Performance is critical (use `undici.request` for maximum speed)

- You want better error handling and debugging capabilities

- You need HTTP/1.1 pipelining or advanced interceptors

* **onRequestStart** `(controller: DispatchController, context: object) => void` - Invoked before request is dispatched on socket. May be invoked multiple times when a request is retried when the request at the head of the pipeline fails.

* **onRequestUpgrade** `(controller: DispatchController, statusCode: number, headers: Record<string, string | string[]>, socket: Duplex) => void` (optional) - Invoked when request is upgraded. Required if `DispatchOptions.upgrade` is defined or `DispatchOptions.method === 'CONNECT'`.

* **onResponseStart** `(controller: DispatchController, statusCode: number, headers: Record<string, string | string []>, statusMessage?: string) => void` - Invoked when statusCode and headers have been received. May be invoked multiple times due to 1xx informational headers. Not required for `upgrade` requests. Any return value is ignored.

* **onResponseData** `(controller: DispatchController, chunk: Buffer) => void` - Invoked when response payload data is received. Not required for `upgrade` requests.

* **onResponseEnd** `(controller: DispatchController, trailers: Record<string, string | string[]>) => void` - Invoked when response payload and trailers have been received and the request has completed. Not required for `upgrade` requests.

* **onResponseError** `(controller: DispatchController, error: Error) => void` - Invoked when an error has occurred. May not throw.

const { Client, interceptors } = require("undici");

const { redirect } = interceptors;

const client = new Client("http://service.example").compose(

redirect({ maxRedirections: 3, throwOnMaxRedirects: true })

);

client.request({ path: "/" })

const { Client, interceptors } = require("undici");

const { retry } = interceptors;

const client = new Client("http://service.example").compose(

retry({

maxRetries: 3,

minTimeout: 1000,

const { Client, interceptors } = require("undici");

const { dump } = interceptors;

const client = new Client("http://service.example").compose(

dump({

maxSize: 1024,

})

const { Client, interceptors } = require("undici");

const { responseError } = interceptors;

const client = new Client("http://service.example").compose(

responseError()

);

const { Client, interceptors } = require("undici");

const { decompress } = interceptors;

const client = new Client("http://service.example").compose(

decompress()

);

const { Client, interceptors } = require("undici");

const { decompress } = interceptors;

const client = new Client("http://service.example").compose(

decompress({

skipErrorResponses: false, // Decompress 5xx responses

skipStatusCodes: [204, 304, 201] // Skip these status codes

- `cacheByDefault` - The default expiration time to cache responses by if they don't have an explicit expiration and cannot have an heuristic expiry computed. If this isn't present, responses neither with an explicit expiration nor heuristically cacheable will not be cached. Default `undefined`.

- `type` - The [type of cache](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Caching#types_of_caches) for Undici to act as. Can be `shared` or `private`. Default `shared`. `private` implies privately cacheable responses will be cached and potentially shared with other users of your application.

**Usage with `fetch`**

const { Agent, cacheStores, interceptors, setGlobalDispatcher } = require('undici')

const client = new Agent().compose(interceptors.cache({

store: new cacheStores.MemoryCacheStore({

maxSize: 100 * 1024 * 1024, // 100MB

maxCount: 1000,

maxEntrySize: 5 * 1024 * 1024 // 5MB

})

}))

setGlobalDispatcher(client)

const first = await fetch('https://example.com/data')

const second = await fetch('https://example.com/data')

The `deduplicate` interceptor deduplicates concurrent identical requests. When multiple identical requests are made while one is already in-flight, only one request is sent to the origin server, and all waiting handlers receive the same response. This reduces server load and improves performance.

- `methods` - The [**safe** HTTP methods](https://www.rfc-editor.org/rfc/rfc9110#section-9.2.1) to deduplicate. Default `['GET']`.

- `skipHeaderNames` - Header names that, if present in a request, will cause the request to skip deduplication entirely. Useful for headers like `idempotency-key` where presence indicates unique processing. Header name matching is case-insensitive. Default `[]`.

- `excludeHeaderNames` - Header names to exclude from the deduplication key. Requests with different values for these headers will still be deduplicated together. Useful for headers like `x-request-id` that vary per request but shouldn't affect deduplication. Header name matching is case-insensitive. Default `[]`.

- `maxBufferSize` - Maximum bytes buffered per paused waiting deduplicated handler. If a waiting handler remains paused and exceeds this threshold, it is failed with an abort error to prevent unbounded memory growth. Default `5 * 1024 * 1024`.

**Usage**

const { deduplicate, cache } = interceptors;

const client = new Client("http://service.example").compose(

deduplicate()

);

const clientWithCache = new Client("http://service.example").compose(

deduplicate(),

cache()

);

* As an iterable that can encompass `Headers`, `Map`, or a custom iterator returning key-value pairs.

Keys are lowercase and values are not modified.

Undici validates header syntax at the protocol level (for example, invalid header names and invalid control characters in string values), but it does not sanitize untrusted application input. Validate and sanitize any user-provided header names and values before passing them to Undici to prevent header/body injection vulnerabilities.

When using the array header format (`string[]`), Undici processes only indexed elements. Additional properties assigned to the array object are ignored.

Response headers will derive a `host` from the `url` of the [Client](/docs/docs/api/Client.md#class-client) instance if no `host` header was previously specified.

| `InformationalError` | `UND_ERR_INFO` | expected error with reason |

| `ResponseExceededMaxSizeError` | `UND_ERR_RES_EXCEEDED_MAX_SIZE` | response body exceed the max size allowed |

| `SecureProxyConnectionError` | `UND_ERR_PRX_TLS` | tls connection to a proxy failed |

| `MessageSizeExceededError` | `UND_ERR_WS_MESSAGE_SIZE_EXCEEDED` | WebSocket decompressed message exceeded the maximum allowed size |

Be aware of the possible difference between the global dispatcher version and the actual undici version you might be using. We recommend to avoid the check `instanceof errors.UndiciError` and seek for the `error.code === '<error_code>'` instead to avoid inconsistencies.