Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 39 ยท Fetch Fundamentals

The Response Object

Explore the fetch Response: ok, status, statusText, headers, url and redirected, the body readers, why a body can be read only once, and how clone() helps.

Every fetch() promise resolves to a Response object. It is the browser's description of what the server answered: a status code, a set of headers, and a body that you read when you need it. Understanding it well explains most fetch behavior, including the classic "body stream already read" error.

You can also create Response objects yourself with new Response(body, init). That is how this lesson, and most test code, can explore the API without a network. Everything you learn here applies identically to responses from real servers. For the reference page, see Request and Response.

Status information

Four properties describe the outcome at the HTTP level.

Property Meaning Example
status The numeric HTTP status code 200, 404, 503
statusText The reason phrase sent by the server "OK", "Not Found"
ok true when status is 200 to 299 true / false
type Where the response came from: basic, cors, opaque, ... "basic"
JS Status, ok and statusText

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

No output.

Notice that a plain new Response('fine') has statusText "", because it was not given one. Servers speaking HTTP/2 or HTTP/3 do not send a reason phrase at all, so never branch on statusText. Use status and ok.

Headers

response.headers is a Headers object: a case-insensitive collection of the response headers. Read a header with get(), test it with has(), and loop over all of them. The name lookup is case-insensitive, because HTTP header names are.

JS Reading headers

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

No output.

Headers are listed in lowercase and sorted. A missing header returns null, not undefined or an empty string. One caution about the real browser: for cross-origin responses you can read only a short list of "safe" headers unless the server exposes more with Access-Control-Expose-Headers. More on that in Headers, Auth and CORS Basics.

A very common use is checking the Content-Type before choosing how to read the body:

JavaScript
const type = response.headers.get('content-type') ?? '';
const data = type.includes('application/json')
  ? await response.json()
  : await response.text();

url and redirected

response.url is the final URL after any redirects, and response.redirected tells you if the request was redirected at all. fetch follows redirects automatically by default (redirect: 'follow'). Responses you build yourself have an empty url, so we only show the idea in a read-only snippet:

JavaScript
const response = await fetch('/old-path');
console.log(response.redirected); // true if the server sent 301/302/307/308
console.log(response.url);        // e.g. "https://example.com/new-path"

This is useful for noticing that a login redirect replaced your API response with an HTML page: redirected is true and the url points at the login form.

Body readers

The body is read with one of these methods. Each returns a promise and gives you a different view of the same bytes:

  • json() parses the text as JSON.
  • text() decodes the bytes as UTF-8 text.
  • blob() gives a Blob with a MIME type, good for images and downloads.
  • arrayBuffer() gives the raw bytes.
  • formData() parses form-encoded or multipart bodies.
JS Five ways to read a body

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

No output.

Response.json() sets Content-Type: application/json, which is why blob.type is application/json. For text(), the encoding is always UTF-8, regardless of what the Content-Type charset says.

A body can be read only once

The body is a stream, not a stored string. Once you have consumed it, it is gone. bodyUsed tells you whether that has already happened.

JS The one-time body

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

No output.

The error is a TypeError saying the body has already been read (the exact wording differs between engines). A typical way to hit this in real code is to read the body to log it, and then try to read it again to use it:

JavaScript
console.log(await response.text()); // consumes the body
const data = await response.json(); // TypeError
flowchart LR
  A["Response<br/>bodyUsed: false"] -->|"json() / text() / ..."| B["Response<br/>bodyUsed: true"]
  B -->|"read again"| C["TypeError"]
  A -->|"clone() first"| D["Two independent bodies"]

Reading consumes the stream. Clone before reading if you need the body twice.

clone(): reading the body twice

response.clone() makes a second Response with its own copy of the body stream. Clone before you read. Then each copy can be read once, independently.

JS Cloning a response

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

No output.

Cloning a large body makes the browser buffer data for both copies, so do it only when you really need two readers. A common legitimate use is a caching layer: store a clone in a cache and return the original to the caller.

Putting it together

A small helper that reports everything interesting about a response is a good debugging tool, and shows how the properties relate:

JS A response inspector

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

No output.

The 204 No Content case has an empty body. Calling json() on it would fail, so check for 204 (or an empty text()) before parsing.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which Response property is true for every status from 200 to 299?

    ok is a convenience boolean: true when status is in the 200 to 299 range.
  2. 2. What does headers.get('etag') return when the header is not present?

    Headers.get returns null for a missing header, so you can use ?? to provide a default.
  3. 3. Why does reading response.json() twice fail?

    A body can be consumed only once. bodyUsed becomes true, and a second read throws a TypeError.
  4. 4. When must you call response.clone()?

    Cloning copies the unread stream. After the body is consumed, clone() throws.

Summary

  • A Response carries status, ok, statusText, headers, url, redirected and a one-time body.
  • Branch on status or ok, never on statusText.
  • headers.get() is case-insensitive and returns null for missing headers.
  • Pick a body reader (json, text, blob, arrayBuffer, formData) by the Content-Type.
  • The body can be read once; bodyUsed shows it, and clone() before reading gives you a second copy.
  • You can build your own responses with new Response() and Response.json() for tests and mocks.

Next: Handling Errors in fetch.