Skip to content
Tutorials Center
My learning

Topics

Lesson 50 of 133 ยท Networking and HTTP

HTTP Clients: fetch and http.request

Make HTTP requests in Node.js with fetch and http.request - headers, JSON and form bodies, error handling, timeouts with AbortSignal, redirects, streaming, retries and keep-alive agents.

Almost every Node.js program talks to some other service: a payment API, a database over HTTP, another microservice of your own. Node gives you two ways to make HTTP requests. The modern one is fetch, the same function you know from browsers, available as a global. The older, lower-level one is http.request from node:http, which gives you direct control over sockets and connection reuse.

This lesson teaches both, with the traps that surprise people: fetch does not reject on a 404, a response body can be read only once, requests have no timeout unless you add one, and connections are pooled. All the examples call a server that runs in the same program on loopback (127.0.0.1), as taught in The http Module: Servers. Our editor has no external network, so a request to a real website fails; we show what that looks like further down.

To keep the examples short, each one starts a small server and prints results from the client side.

fetch in Node

fetch(url, options) returns a promise for a Response. The promise resolves as soon as the headers have arrived; the body is read afterwards with response.text(), response.json(), response.arrayBuffer(), response.blob() or response.body (a stream). Node's fetch is powered by a library called undici, and follows the web standard, so code is portable between the browser and Node.

Node.js The anatomy of a Response

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

response.headers is a case-insensitive Headers object: get, has and iteration all work with lower-case names. response.ok is true for statuses 200 to 299.

Sending data: methods, headers and bodies

The options object takes method, headers and body. The body can be a string, a URLSearchParams (sent as a form), a FormData (multipart), a Blob, a Buffer or typed array, or a stream. When you pass a string you must set the Content-Type yourself. With URLSearchParams and FormData, fetch sets it for you.

Node.js Posting JSON, a form and multipart data

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Query strings are best built with URL and URLSearchParams so that special characters are escaped correctly. See URLs, URLSearchParams and URLPattern.

NODE
const url = new URL('https://api.example.com/search');
url.searchParams.set('q', 'fish & chips');
url.searchParams.set('page', '2');
// url.href is https://api.example.com/search?q=fish+%26+chips&page=2

Errors: what fetch rejects, and what it does not

This is the most important thing to learn about fetch:

  • HTTP errors do not reject. A 404 or 500 is a perfectly good response, so the promise resolves. You must check response.ok or response.status yourself.
  • Network failures reject with a TypeError: fetch failed, whose cause holds the real reason (ECONNREFUSED, ENOTFOUND, ECONNRESET, ...).
Node.js 404 resolves, a closed port rejects

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

For a request to a real host from inside our editor you would see the same TypeError: fetch failed, with a DNS-related cause.code (the exact code depends on the machine). That is the sandbox telling you there is no outside network, not a bug in your code.

The body can be read only once

A response body is a stream, so it can be consumed only one time. Reading it twice throws. If you need it twice, call response.clone() before reading either.

Node.js Reading a body twice (fails on purpose)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The last line throws TypeError: Body is unusable: Body has already been read. Calling clone() first, as the code above does for copy, is the way to keep a second copy.

Also remember to consume or cancel every response body (even a HEAD-like check): an unread body keeps its connection busy. If you do not need it, call await response.body?.cancel().

Timeouts and cancellation

fetch has no timeout by default. A server that accepts the connection and never answers would make your await wait for ever. Always pass an AbortSignal: AbortSignal.timeout(ms) aborts after a deadline, and an AbortController lets you cancel on demand (for example when the user closes a page). The signal also covers reading the body. More in AbortController and Cancellation.

Node.js Timeout and manual cancellation

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Note the two different error names: TimeoutError for a deadline and AbortError for a manual abort(). Code that retries should retry on timeouts but not when the user cancelled on purpose.

Redirects

By default fetch follows up to 20 redirects and sets response.redirected to true; response.url is the final address. You can control that with the redirect option: 'follow' (default), 'manual' (return the 3xx response so you can read Location) or 'error' (reject).

Node.js Following and not following redirects

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

For security, fetch removes the Authorization header when a redirect goes to a different origin. Keep that in mind if you set the option to manual and follow the redirect yourself.

Streaming a response

response.body is a web ReadableStream, and in Node it is async-iterable, which lets you process a large download piece by piece instead of loading it into memory. To mix it with Node streams, use Readable.fromWeb(response.body); see Web Streams in Node.js.

Node.js Counting bytes of a streamed download

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The total is always the same (1000 lines of 101 bytes) even though the number of chunks is not predictable.

http.request: the low-level client

http.request(options, callback) is how things were done before fetch, and it is still useful when you need things fetch hides: choosing the agent, reading raw sockets, sending unusual methods, or very precise streaming. It returns a writable ClientRequest; the callback receives an IncomingMessage response (a readable stream, like req on the server). You must call req.end() to send the request.

Node.js The same request with http.request

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The shape differs from fetch: callbacks instead of promises, headers as a plain lower-case object, status as res.statusCode, and error handling on the request object (req.on('error', ...)). A request without an 'error' listener crashes the process on network failure. For nearly all new code prefer fetch; reach for http.request when you need the control.

Agents and keep-alive

Opening a TCP connection (and for HTTPS, a TLS handshake) is slow compared with sending a request. An agent pools connections and reuses them for later requests to the same host. Since Node 19 the default agent uses keep-alive, and fetch has its own pool inside undici. The next example counts how many TCP connections the server saw for three sequential requests, with an agent that reuses connections and one that does not.

Node.js Counting connections with and without keep-alive

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The agent has tuning options:

Option Meaning
keepAlive Keep sockets open after a request so later requests reuse them
keepAliveMsecs Initial delay for TCP keep-alive probes on pooled sockets (default 1000)
maxSockets Most simultaneous connections per host (default unlimited)
maxTotalSockets Most simultaneous connections across all hosts
maxFreeSockets Most idle sockets kept per host (only with keepAlive)
timeout Socket timeout in milliseconds

Each request also tells you whether it got a recycled socket: request.reusedSocket is true when keep-alive handed it an existing connection.

Node.js Agent options and reusedSocket

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Reusing connections matters most for servers that call the same API thousands of times. Two cautions: pooled sockets keep your process alive, so call agent.destroy() (or unref your usage) in short scripts; and a server may close an idle connection just as you try to reuse it, so an occasional ECONNRESET on a reused connection is something retry logic should expect.

Retrying: a small, careful helper

Networks fail. A good client retries idempotent requests (like GET) on temporary failures, waits a bit longer each time (exponential backoff), and gives up after a few attempts. This example uses a server that fails twice before succeeding, with tiny delays so it finishes quickly. A fuller treatment is in Concurrency Control and Queues.

Node.js Retry with backoff on 503

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Never retry blindly: only repeat requests that are safe to repeat, respect Retry-After, add random jitter in real systems so that many clients do not retry in lockstep, and set an overall time limit.

Pitfalls and habits

  • Check response.ok. Do not assume success from a resolved promise.
  • Always set a timeout with AbortSignal.timeout().
  • Consume or cancel bodies, and read each body once (or clone() first).
  • Set Content-Type yourself when sending a string body.
  • Build URLs with URL and URLSearchParams, never by gluing user input into a string.
  • Never fetch URLs supplied by users unchecked. Requests from your server to internal addresses (server-side request forgery, "SSRF") are a classic security hole; see Web Application Security.
  • Keep secrets out of logs. Do not log Authorization headers or full URLs that contain tokens.
  • Write tests against a local server, as these examples do; Testing HTTP Servers and CLIs shows the pattern.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does fetch() do when the server answers with status 500?

    HTTP error statuses are valid responses. Only network-level failures reject, so you must check response.ok.
  2. 2. What happens if you call response.text() twice on the same response?

    A body is a one-shot stream. Use response.clone() before reading if you need it twice.
  3. 3. Which option gives a fetch call a 5-second deadline?

    fetch has no timeout option. AbortSignal.timeout() creates a signal that aborts with a TimeoutError after the delay.
  4. 4. Why attach an 'error' listener to the object returned by http.request()?

    ClientRequest is an EventEmitter, so an 'error' event with no listener is thrown as an uncaught exception.
  5. 5. What is the main benefit of an http.Agent with keepAlive true?

    Reusing connections avoids repeating the TCP (and TLS) handshake for every request.

Summary

  • fetch is a global in Node; it resolves for any HTTP status and rejects only on network failures (TypeError: fetch failed, with the real code in error.cause).
  • Check response.ok, read the body once (json(), text(), or stream response.body), and clone() if you need two reads.
  • Send bodies as strings (set Content-Type), URLSearchParams, FormData, Blobs, buffers or streams.
  • Add AbortSignal.timeout() to every request; manual cancellation uses AbortController.
  • Redirects are followed by default; use redirect: 'manual' to inspect them.
  • http.request is the low-level, callback-based client with agents; keep-alive pools connections.
  • Retry only safe requests, with backoff and a limit.

Next: Building a Router from Scratch