Skip to content

fetch() ​

The fetch() function sends an HTTP request and returns a Promise. The Promise fulfills with a Response when the server's status code, response headers, and first chunk of the response body arrive.

The request runs in the background. While waiting, JS keeps running and the interface stays responsive. Requests don't depend on the interface: they can be sent from anywhere after the app launches, including the top level of a file, without waiting for sceneconnect. fetch() can request any server and isn't subject to cross-origin rules.

Classes used together with fetch():

For how to use these classes for common tasks, see the guides Fetching data from the network and Reading a response as it downloads.

Functions ​

fetch()

Sends a request and returns a Promise that fulfills with a Response.

Examples ​

The code below requests a URL that returns JSON and prints the result to the console. The whole thing can go at the top level of main.js.

js
async function load() {
  // 1. Send the request. This line returns when the headers and first chunk arrive
  const res = await fetch('https://httpbin.org/get');

  // 2. Check whether the server returned a success status
  if (!res.ok) {
    console.log('Server returned an error:', res.status);
    return;
  }

  // 3. Read the response body and parse it as JSON
  const data = await res.json();
  console.log(res.status, data.url);
}

// 4. fetch fails when the network is down; catch it
load().catch((err) => {
  console.log('The request was not sent or no response was received:', err.message);
});

Result

  • When the network is working, the console prints 200 https://httpbin.org/get.
  • When the server returns 404 or 500, it prints Server returned an error: 404.
  • When there is no network or the server can't be reached, it prints The request was not sent or no response was received: followed by an error description.

Steps 2 and 4 handle two different kinds of failure; see When a request counts as failed.

Note: await can only be written inside an async function. You can't write await directly at the top level of a file.

Differences from the web ​

The names in the fetch group of APIs are the same as on the web. The differences are listed one by one under "Differences from the web" on each member page; this table collects them for people familiar with the web.

WebNacre
await fetch(url, init)Same. url must be a full URL
fetch() fulfills when the response headers arriveFulfills when the first chunk of the body arrives
init.body can be a string, Blob, ArrayBuffer, typed array, or URLSearchParamsSame
init.body can be FormData or ReadableStreamNot available
When body is an ArrayBuffer without Content-Type, that header isn't sentThe system fills in application/x-www-form-urlencoded
init.mode, init.credentials, init.cache, init.redirectNot available; writing them has no effect
CORS preflight, same-origin policyNone; any URL can be requested
Headers such as Host and Cookie can't be setAll can be set
Cancellation throws signal.reason, a DOMException by defaultThrows an Error whose name is 'AbortError'. There is no DOMException class
After AbortSignal.timeout() runs out, fetch() throws TimeoutErrorThrows AbortError
res.statusTextAlways the empty string on responses from fetch()
res.text() decodes using the encoding the response declares, replacing invalid bytes with the replacement characterAlways decodes as UTF-8; gives an empty string when invalid
The type of res.blob() comes from Content-Typetype is the empty string
res.formData(), res.clone()Not available
req.bodyNot available. A Request's body can only be read with the four reading methods
new Blob([blob])Throws TypeError
read() rejects with signal.reason when the request is canceledRejects with AbortError
reader.closed fulfills when the body reaches its endFor streams from fetch(), it fulfills only after read() reaches done
Buffering is limited even when not reading; the download stops to waitLimited only after you start reading with read(); downloading continues until then
A truncated response without Content-Length reports an errorNo error when the server closes the connection normally
new ReadableStream(…), pipeTo(), pipeThrough(), tee(), getReader({ mode: 'byob' })Not available
WritableStream, TransformStream, EventSourceNot available

See also ​