How Does fetch Work?

Fetch takes a URL and returns a promise that resolves with a Response object. The request is sent in the background, so the calling code continues immediately and handles the outcome later. Because the request itself is asynchronous, the promise almost always resolves with the response headers first, and you read the body separately.

// The Response object is what fetch resolves with.
// You can build one locally to try this without a network.
const response = new Response(JSON.stringify({ name: "Ada", id: 7 }), {
  status: 200,
  headers: { "Content-Type": "application/json" },
});

async function readProfile() {
  // A real call would be: const response = await fetch("/api/profile");
  if (!response.ok) {
    throw new Error(`Request failed with status ${response.status}`);
  }
  return response.json();
}

readProfile()
  .then((profile) => console.log(profile.name, profile.id))
  .catch((err) => console.log("failed:", err.message));

Two parts of the API trip people up on their first use. The body has to be read explicitly, and you read it exactly once, with the method that matches its type: the json method for JSON, the text method for text, and the blob or arrayBuffer methods for binary data. The body is a stream, so reading it twice fails.

The second is the options object. It carries the method, the headers, the body and the credentials mode, and for anything other than a simple GET request the body has to be a string, a URL encoded form, a Blob or an array buffer. Sending an object does not serialise it for you; you have to call the json method on the request options or stringify it yourself.

Fetch also supports an abort signal, which is how you cancel a request that is no longer needed. Creating an abort controller and aborting it makes the fetch promise reject with an abort error, and the browser also stops the network request rather than just ignoring the result.

No. This is the single most common misunderstanding about fetch. The promise rejects only when the request could not be made at all, for example when the network is down, the domain does not resolve or the browser blocks the request because of cross-origin rules. A response with an error status is a perfectly successful round trip, so the promise resolves.

That is why you have to check the response yourself. The ok property is true for statuses in the two hundreds and false for everything else, and the status and statusText properties give you the detail. Checking ok is the standard pattern, and wrapping it in a helper that throws an error is what most codebases end up with, so that every caller gets a rejected promise for a failed request.

There is one exception to remember. A request that is aborted through an abort signal rejects with an abort error, and that is a deliberate rejection rather than a failed response. You usually want to catch that one separately so it does not get reported as a genuine failure.

The reason the API is designed this way is that an HTTP error status is a meaningful response that the application should interpret. A 404 might be an expected outcome that you want to render as an empty state, and a 500 might be worth retrying. If fetch rejected on every non-two-hundred status, you would lose the body and the headers, and you would have to invent a way to get them back. The design puts the decision about what counts as a failure in the hands of the application, which is the right place for it.