Your first API call

A ticket at the counter

You order a drink at a counter. The staff do not make you stand there and watch. They hand you a numbered ticket, you do something else, and you come back when your number is called.

fetch works the same way. One round trip over the network often takes hundreds of milliseconds, and JavaScript runs on a single thread, so it cannot stop and wait. The moment fetch(url) runs, it returns an object that stands for a result which has not arrived yet and which will later either succeed or fail. That object is called a Promise. When the response arrives, the Promise settles: it either resolves with a value or rejects with an error.

Why two awaits?

The two awaits wait for two different things. The first one, await fetch(url), resolves as soon as the response headers have arrived. At that point you can read res.status and res.headers, but the body may still be downloading. The second one, await res.json(), reads the body and parses it into a JavaScript value. Reading the body is a separate asynchronous step, so res.json() returns a Promise of its own.

Three notes. ① await normally has to be inside an async function; ES modules and the browser console also allow it at the top level, which is why you can type it straight into the console for the practice tasks. ② An async function always returns a Promise, whatever value you return inside it. ③ So whoever calls it usually has to await it too. async spreads outward along the call chain. That is expected, not a mistake.

'Success' means something narrower than you expect

You might expect 404 and 500 to jump into catch. They do not. For fetch, the call succeeded if the request reached the server and a response came back — even when that response says 404. The Promise from fetch rejects only when the request fails at the network level: no connection, a hostname that does not resolve, a request that was aborted, or a response the browser blocked under the CORS rules.

So you have to check the status yourself. res.ok is true when the status code is between 200 and 299. Skip that check and the body of a 404 response gets passed along as if it were normal data. The program then fails much later, far from the real cause, usually with a string of undefined.

res.json() can fail on its own

res.json() reads the response body and parses it as JSON. If the body is not valid JSON, the Promise it returns rejects with a SyntaxError. This happens more often than you would expect. A misconfigured server can answer with an HTML error page and still send status 200, so res.ok is true and the parse fails. An empty body does the same: a 204 No Content response has no body, so calling res.json() on it fails.

Notice that the example above writes return await res.json(), not return res.json(). With the await, the parse happens inside the try block, so this error lands in the same catch as everything else. Without it, the Promise would leave the function before try could see it fail.

Leave one part out and it breaks

Without JSON.stringify, fetch converts the object to a string the ordinary JavaScript way, and the server receives the text [object Object]. Not one field can be read out of it. Without Content-Type, the server may try to parse your JSON as plain text or as form data; the fields come out empty, or the server answers 400. Without method, the request is a GET, and a GET is not allowed to carry a body, so fetch throws a TypeError before anything is sent. The wording differs between browsers; Chrome says Request with GET/HEAD method cannot have body. That one is easy to notice, because it lands in catch immediately. The first two are much quieter.

When a server says it received nothing, check these three first. Most of the time one of them is missing.

A response body can only be read once

res.json() reads the body as a stream: the data passes through once and is then gone. Calling res.json() a second time on the same response throws TypeError: body stream already read. If you need the data twice, store it the first time: const data = await res.json(). If you really need to read the raw body twice, res.clone() gives you a second copy, but you have to call it before either copy is read. DevTools can show you the body again because the browser kept its own copy, not because your code gets a second chance.

The same-origin policy in one paragraph

Browsers follow a rule called the same-origin policy: a script loaded from one origin may not read a response from a different origin, unless that response says it is allowed. The response says so with a header, Access-Control-Allow-Origin. The set of rules around that header is called CORS (Cross-Origin Resource Sharing).

Two things follow from this. First, the browser enforces the rule, so it protects the user, not the server: curl, Postman, and any program running on a server ignore CORS entirely, and the header keeps nobody out. Second, a CORS failure is not an HTTP error status. There is no CORS status code. The response may well have been 200; the browser simply did not hand it to your code, so the fetch Promise rejects and the explanation is printed in the console.

The public APIs used in this chapter — PokeAPI, JSONPlaceholder, and Open-Meteo — all send the header, so they work from a page. Who blocks what, how a server allows an origin, and what an OPTIONS preflight request is are covered in chapter 06, together with authentication.