Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Web APIs in Node.js

Node.js Response class

Reference for the Response class in Node.js: read status, headers and body from fetch(), parse json() and text(), stream bodies, and build your own.

A Response represents an HTTP response: a status code, headers and a body. Every fetch() call resolves to one, and you can also construct your own, which is how web-standard server handlers and test doubles produce answers.

The status and headers are available immediately. The body is a one-shot stream that you read with text(), json(), arrayBuffer(), bytes(), blob() or formData(), or process chunk by chunk through response.body. Response is a global class and works the same as in browsers.

NODE
const response = new Response('hello', { status: 201 });
console.log(response.status, await response.text()); // 201 hello

Try it

Node.js Building and reading responses

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.

Node.js Streaming a body and handling errors

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.

Syntax

NODE
new Response([body[, init]])
Response.json(data[, init])
Response.error()
Response.redirect(url[, status])

body may be a string, Buffer/typed array, ArrayBuffer, Blob, FormData, URLSearchParams, a ReadableStream, or null. init has status (default 200), statusText (default '') and headers.

Property Description
status The status code.
statusText The reason phrase (often empty over HTTP/2 or when you did not set it).
ok true for statuses 200 to 299.
headers A Headers object (read-only for responses from fetch()).
url The final URL after redirects, or '' for a response you built.
redirected true if at least one redirect was followed.
type 'default', 'basic', 'cors', 'error', 'opaque' or 'opaqueredirect'. Responses you construct are 'default'; fetch() in Node returns 'basic'.
body A ReadableStream of Uint8Array chunks, or null.
bodyUsed true once reading has started.
Method Description
text() Promise for the body decoded as UTF-8.
json() Promise for the parsed JSON; rejects with SyntaxError for invalid JSON.
arrayBuffer(), bytes(), blob() Binary forms.
formData() Parse a multipart or urlencoded body into FormData.
clone() A copy with an independent body (throws if the body was already used).

Errors: RangeError for a status outside 200 to 599 in the constructor (or a redirect status other than 301, 302, 303, 307, 308); TypeError for a body with a null-body status (101, 204, 205, 304), for reading a used body, or for an invalid redirect URL.

Usage notes

  • Response.json() sets content-type: application/json and serializes with JSON.stringify.
  • Bodies are single-use. After text() the body is gone; call clone() before reading when two consumers need the data. Clones tee the stream, so a very slow second reader makes the buffered data grow.
  • Do not leave bodies unread. From fetch(), an unread body holds the connection; call await response.body?.cancel() when you only care about the status.
  • response.ok is a status check only. A 404 is a normal response; check ok before json().
  • json() tolerates a leading byte-order mark but not an empty body: an empty string is a SyntaxError. Check the status and content-length, or use text() first.
  • Text decoding is always UTF-8, whatever the charset in the header says. For other encodings use arrayBuffer() with a TextDecoder.
  • Stream chunks are Uint8Array, not Buffer and not strings. Decode with TextDecoder using { stream: true } so multi-byte characters can span chunks.
  • Response.redirect() needs an absolute URL in Node (no base), and Response.error() is for service-worker-style handlers; neither is common in plain scripts.
  • bytes() arrived in Node 22.