Fetch API, do you really know how to handle errors?

The Fetch API is not that new and most developers have used it at some point to retrieve resources from a server, but do you really know how to handle errors when using this API?

Given the code below, in which a request using the Fetch API returns a 404 error, what would be the message in the console: successful or failed?

try {
  // this endpoint will return 404
  const response = await fetch('https://restcountries.com/v4.1/all');
  console.log('Success');
} catch {
  console.error('Failed');
}

If you assume this code logs the failed message when a 404 error occurs, I’d say this article is definitely for you because your answer is wrong. The console.log will display the successful message and I’ll tell you why and what’s the best way to handle errors using the Fetch API.

What’s Fetch API?

In short, the Fetch API is an interface for easily making asynchronous HTTP GET and POST requests to endpoints.

I really recommend you read this article I wrote a while ago called “Fetch API is new old version of AJAX”, where I explained better what Fetch API is and how to use it along with the async/await syntax, so feel free to check out for more explanation about this API.

How to handle errors using Fetch API?

When using the Fetch API different errors may occur, such as: server error (500), not found error (404), network error, CORS error and so on. And we have different approaches to handle all these errors, as you can see below.

Using try/catch to handle Fetch API errors

I'm assuming you're familiar with promises in JavaScript and know how they work (because one of the reasons the Fetch API is so popular is because it returns a promise). Therefore, we can use the power of then, catch and finally when the fetch is resolved, rejected and finished.

Wrapping the fetch call in a try/catch block is a very common way of handling errors (see example below), but not all errors can be caught and I will explain this just after the code.

try {
  // this endpoint will return CORS error
  const response = await fetch('https://google.com/api');
} catch {
  console.error('Failed');
}
// Output: Failed

This code will attempt to perform a fetch and detect errors only when the promise is rejected (which can occur in two scenarios):

• network errors: failure to connect to the server which can be caused by several reasons, such as slow network and timeout, for example.
• CORS errors: when a domain is not authorised to obtain resources from a different domain.

Fetch will return resolved for server status errors (like 404 and 500 for instance), that's the reason why catch can't get them in the example at the beginning of this article.

Checking the response status to handle Fetch API errors

Another common way to handle errors using the Fetch API is to check the response status when the promise resolves - and this is how we should get the 404 error in the example at the beginning of this article:

// this endpoint will return 404
const response = await fetch('https://restcountries.com/v4.1/all');

if (response.ok) {
  // ...do something with the response if response.ok is true
} else {
  console.error('Failed');
}

Here we use response.ok to check if the response was successful or not (true or false).

• it is true when the status code is between 200 and 299 (it means successful).
• it is false when the server returns any other status than the above. Examples are 404 (not found) and 500 (internal server error).

Best way to handle errors using Fetch API

Example 01

As you saw above, try/catch and response.ok are used to catch different types of errors, so we can combine the two approaches to better handle errors using the Fetch API. See example below:

try {
  const response = await fetch('https://restcountries.com/v4.1/all');
  if (response.ok) {
    console.log('Promise resolved and HTTP status is successful');
    // ...do something with the response
  } else {
    console.error('Promise resolved but HTTP status failed');
  }
} catch {
  console.error('Promise rejected');
}

Explanation:

• try/catch is used to get errors when the promise gets rejected (network or CORS issues)
• response.ok is used to handle server errors (404 or 500, for example) when the promise gets resolved

Example 02

Another common way to handle erros inside the try block is throwing an error when response.ok isn’t true in order to make the catch block be executed, so that we can handle all errors at the same place. See example bellow for a better understanding:

try {
  const response = await fetch('https://restcountries.com/v4.1/all');

  if (response.ok) {
    console.log('Promise resolved and HTTP status is successful');
    // ...do something with the response
  } else {
    // Custom message for failed HTTP codes
    if (response.status === 404) throw new Error('404, Not found');
    if (response.status === 500) throw new Error('500, internal server error');
    // For any other server error
    throw new Error(response.status);
  }
} catch (error) {
  console.error('Fetch', error);
  // Output e.g.: "Fetch Error: 404, Not found"
}

Here we throw errors to handle them in the catch block and also display a custom message in the console depending on the type of error.

• when response.ok returns false, we can simple throw an error, so the catch block will be executed
• catch will then handle all types of errors
• catch accepts an argument that can be customized when throwing errors from the try block
• response.status can be used to check the returned HTTP status code to display customized messages in the console (like 400, 404, 500…).

References

• “Response: ok property” by MDN
• “HTTP response status codes” by MDN
• “Using the Fetch API” by MDN
• “Implement error handling when using the Fetch API” by web.dev

Conclusion

It is very important to handle all errors that may occur when using Fetch API when retrieving resources from the server and here I have explained how to use try/catch along with response.ok and response.status to get different errors and also customize the way we are dealing with them.

See you next time! 😁