Response
Response represents the response to an HTTP request: the status code, the response headers, and the response body. You get it when the Promise returned by fetch() fulfills.
The status code and headers are complete when you get the Response. The body may still be downloading: read it whole with one of the four reading methods, or chunk by chunk with body. The body can be read only once; see The body can be read only once.
You can also create a Response yourself, to stand in for a real request in tests.
Inheritance: Response doesn't inherit from other classes.
For how to send requests and read responses, see the guide Fetching data from the network.
Constructor
Creates a response with the given body, status code, and headers.
Instance properties
All of these properties are readable and not writable.
| Property | Description |
|---|---|
ok read-only | true when the status code is between 200 and 299 |
status read-only | The status code |
statusText read-only | The text for the status code |
headers read-only | The response headers |
url read-only | The URL the response came from |
body read-only | A stream of the body, for reading while downloading |
bodyUsed read-only | Whether the body has already been read |
redirected read-only | Always false |
type read-only | Always 'basic' |
Instance methods
All four reading methods wait for the whole body to download and return a Promise. Once any one has been used, none of the others can read.
| Method | Description |
|---|---|
json() | Parses as JSON and gives the parsed value |
text() | Decodes as UTF-8 and gives a string |
arrayBuffer() | Gives an ArrayBuffer |
blob() | Gives a Blob; the content doesn't enter JS memory |
Concepts
Choosing among the four ways to read
| Method | What you get | When to use it | Memory |
|---|---|---|---|
json() | The parsed value | JSON returned by an API | Besides the downloaded content, creates a string and the parsed objects |
text() | A string | Text, HTML | Besides the downloaded content, creates a string |
arrayBuffer() | An ArrayBuffer | Binary data you process byte by byte | Creates no string |
blob() | A Blob | Images, video, files you pass straight to another API | Creates no string; the content doesn't enter JS memory |
Downloading and text decoding happen in the background, and the interface stays responsive while waiting.
With the four methods that read the whole body, the downloaded content stays in memory until the Response object is no longer referenced by any variable and is reclaimed. If you don't need the body after getting the Response, cancel the request with AbortController, and the download stops immediately.
When you don't want to wait for the download to finish, read chunk by chunk with body; see Reading a response as it downloads.
The body can be read only once
The four reading methods share one chance: once any one has been used, the others can't read, and the returned Promise rejects: TypeError: Body has already been read. If you need the content twice, store the first result in a variable. Response has no clone().
body and these four methods read the same content, so they exclude each other:
| What was done first | Afterward |
|---|---|
| One of the four reading methods was called | res.body.locked is true, and res.body.getReader() throws TypeError |
res.body was read (read() was called), or canceled (cancel() was called) | res.bodyUsed is true, and the four reading methods reject: TypeError: Body has already been read |
res.body has a reader that hasn't read yet | The four reading methods reject: TypeError: Body is locked: response.body has a reader. res.bodyUsed is still false; after calling the reader's releaseLock(), the four methods work as usual |
Only the res.body property was accessed, without getting a reader | No effect |
Responses without a body
The following Response objects have no body, and their body is null:
- Created yourself with the
bodyargumentnullor omitted; fetch()sent aHEADrequest;fetch()got status code 204, 205, or 304.
Reading a Response without a body gives:
| Method | Result |
|---|---|
text() | The empty string '' |
arrayBuffer() | An ArrayBuffer of 0 bytes |
blob() | A Blob whose size is 0 |
json() | Rejects with SyntaxError. An empty string isn't valid JSON |
In this case bodyUsed stays false, and you can read repeatedly. The empty string '' doesn't count as "no body": it is a body of length 0, body is a stream (the first read() is already done), and after one read bodyUsed is true.
Examples
async function main() {
const res = await fetch('https://httpbin.org/get');
console.log(res.ok, res.status);
console.log(res.headers.get('content-type'));
const data = await res.json();
console.log(data.url);
}
main();Result: It prints true 200, application/json, then https://httpbin.org/get.
Differences from the web
- On responses from
fetch(),statusTextis always the empty string. text()always decodes as UTF-8, and gives an empty string when the bytes are invalid. The web decodes using the encoding the response declares, and replaces invalid bytes with the replacement character.- The
typeof theBlobfromblob()is the empty string. On the web it comes fromContent-Type. redirectedis alwaysfalse, andtypeis always'basic'.- There is no
clone()orformData(), and no static methodsResponse.json(),Response.error(), orResponse.redirect().
See also
fetch(): gets aResponseReadableStream: the type ofbody- Fetching data from the network
- Reading a response as it downloads