Fetch API Errors: Why a 404 is a 'Success'

Why it exists

The Fetch API was designed as a low-level interface for HTTP requests. It intentionally separates network transport failures (like a DNS error or no connection) from application-level HTTP status codes (like 404 or 500). The promise is only rejected for network issues, forcing you to explicitly handle the server's response, whatever it may be.

The mental model

Think of fetch() as confirming a message was delivered, not that the recipient liked the message. The promise resolves successfully if the server receives the request and sends any response back, even a 404 error page. The promise only rejects if the message could not be delivered at all due to a network or connection problem.

How it works

The standard pattern is to wrap your fetch() call in a try...catch block. The fetch() promise resolves with a Response object. This object has a boolean property, response.ok, which is true only for successful HTTP statuses in the 200-299 range. Inside your try block, you must check if (!response.ok). If it's false, you manually throw new Error() with details like response.status. This allows your single catch block to handle both network errors (which cause an automatic rejection) and HTTP status errors (which you throw yourself).

When to use it

Use this try/catch and response.ok check for virtually every fetch call. It is the standard, correct way to handle situations where a server error (like 404 Not Found or 503 Service Unavailable) needs to be handled differently from a successful response.

When not to use it

This pattern is fundamental to using the raw Fetch API. You would only skip this if using a higher-level data-fetching library (like Axios or TanStack Query) that wraps fetch and provides its own, more abstract error handling mechanism.

One canonical example

async function getData() {
const url = "https://example.org/products.json";
try {
const response = await fetch(url);
if (!response.ok) {
throw new Error(Response status: ${response.status});
}
const result = await response.json();
console.log(result);
} catch (error) {
console.error(error.message);
}
}