Fetch catch Doesn't Run on 404: Check Status Before JSON

Put the HTTP check before the JSON parser#

MDN’s fetch reference distinguishes request failures from HTTP error responses. Receiving a 404 response is enough to fulfill the fetch promise; your code decides whether to reject it. The Response.ok property is true for status codes 200 through 299.

For a GET endpoint that promises JSON on success and allows 204 as an empty result, use this helper:

1
async function getJson(url) {
2
  const response = await fetch(url);
3
  if (!response.ok) {
4
    const error = new Error(`HTTP ${response.status}`);
5
    error.name = 'HttpError';
6
    error.status = response.status;
7
    throw error;
8
  }
9
  // This endpoint contract treats 204 as a successful empty result.
10
  if (response.status === 204) return null;
11
  return response.json();
12
}

Await getJson(url) inside your try block, or attach .catch() to its returned promise. The helper throws before attempting to interpret an error body. It does not retain that body; if the API exposes structured error details, add a separate error-body policy after preserving the status.

Returning null for 204 is an application choice. The Fetch Standard defines 204 as a status without a body, but does not prescribe a JavaScript return value for your helper. If your endpoint requires a JSON object on every successful request, treat 204 as a contract violation instead. This example is for GET requests, not a general wrapper for HEAD or every possible bodyless status.

Reproduce the three different error paths#

Save the following as fetch-status-demo.mjs and run node fetch-status-demo.mjs. It uses Node.js 24 and its built-in fetch, starts a loopback HTTP server on an available port, and needs no package or external API. The helper is repeated so the file runs independently.

1
import { createServer } from 'node:http';
2

3
async function getJson(url) {
4
  const response = await fetch(url);
5
  if (!response.ok) {
6
    const error = new Error(`HTTP ${response.status}`);
7
    error.name = 'HttpError';
8
    error.status = response.status;
9
    throw error;
10
  }
11
  // This endpoint contract treats 204 as a successful empty result.
12
  if (response.status === 204) return null;
13
  return response.json();
14
}
15

16
const routes = {
17
  '/ok-json': [200, 'application/json', '{"value":1}'],
18
  '/missing-json': [404, 'application/json', '{"error":"missing"}'],
19
  '/missing-html': [404, 'text/html', '<!doctype html><h1>Missing</h1>'],
20
  '/ok-html': [200, 'text/html', '<!doctype html><h1>App shell</h1>'],
21
  '/empty': [204, null, ''],
22
};
23
const server = createServer((request, response) => {
24
  const [status, type, body] = routes[request.url] ?? routes['/missing-html'];
25
  response.writeHead(status, type ? { 'Content-Type': type } : {});
26
  response.end(body);
27
});
28
await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
29
const base = `http://127.0.0.1:${server.address().port}`;
30

31
async function outcome(operation) {
32
  try {
33
    return `resolved ${JSON.stringify(await operation())}`;
34
  } catch (error) {
35
    return `rejected ${error.name}${error.status ? ` ${error.status}` : ''}`;
36
  }
37
}
38

39
try {
40
  for (const path of Object.keys(routes)) {
41
    const url = base + path;
42
    const response = await fetch(url);
43
    console.log(`${path}: fetch resolved status=${response.status} ok=${response.ok}`);
44
    await response.body?.cancel();
45
    console.log(`  unchecked: ${await outcome(async () => (await fetch(url)).json())}`);
46
    console.log(`  checked:   ${await outcome(() => getJson(url))}`);
47
  }
48
} finally {
49
  await new Promise(resolve => server.close(resolve));
50
}

The exact fixture was executed during preparation on macOS with Node.js 24.13.0 on October 5, 2026. It produced:

1
/ok-json: fetch resolved status=200 ok=true
2
  unchecked: resolved {"value":1}
3
  checked:   resolved {"value":1}
4
/missing-json: fetch resolved status=404 ok=false
5
  unchecked: resolved {"error":"missing"}
6
  checked:   rejected HttpError 404
7
/missing-html: fetch resolved status=404 ok=false
8
  unchecked: rejected SyntaxError
9
  checked:   rejected HttpError 404
10
/ok-html: fetch resolved status=200 ok=true
11
  unchecked: rejected SyntaxError
12
  checked:   rejected SyntaxError
13
/empty: fetch resolved status=204 ok=true
14
  unchecked: rejected SyntaxError
15
  checked:   resolved null

Each operation makes a fresh request. The first response’s body is canceled after reading its metadata, so it is not reused for either parser check. The output prints error classes rather than engine-specific parsing messages.

The important difference is /missing-json: JSON parsing succeeds even though the HTTP status is 404. Without the status check, both the request and parser resolve. With /missing-html, the unchecked parser rejects, but the HTTP failure is disguised as SyntaxError.

Diagnose the layer that failed#

The Response.json() reference documents a SyntaxError when the body cannot be parsed as JSON. Parsing success does not establish HTTP success, and response.ok does not establish a valid JSON payload.

For a real endpoint, inspect those response details in the browser’s Network panel before changing the parser. A 200 HTML body tells you what arrived; it does not by itself prove whether a login redirect, wrong route, or fallback page caused it. The fixture deliberately returns an app shell to demonstrate that boundary.

A rejection from await fetch(url) before a response exists belongs to another branch of the diagnosis. MDN lists network errors, invalid requests, and aborts among fetch failures. The loopback example does not test those failures, browser CORS enforcement, redirects, or service workers; browser behavior should be checked in the affected environment.

For a shell request failing to stop a CI job, use the separate curl HTTP error and pipeline checks. JavaScript promises and shell exit statuses require different fixes.

Keep the order explicit: receive the response, decide whether its status is acceptable, handle an allowed empty result, then parse the promised payload. A catch becomes useful when the code preserves which of those operations failed.

References:

• MDN: Window.fetch()
• MDN: Response.ok
• MDN: Response.json()
• WHATWG Fetch Standard: statuses