Centralizing API error handling in React apps 

In this article I'm going to present to you a way of handling your API errors once and for all in a centralized and easily extendable way, regardless of the state-management library (Redux, Apollo, etc.) that you are using. 

Almost every modern app interacts with an API for their data requirements; be it a RESTful API or a GraphQL one, firing requests on the web is the bread and butter of the majority of apps out there. Most of the times things go well and your request is returns successfully, but there are times when things don't go as smoothly. I'm talking about those dreaded 404s, 403s & 500s that the APIs can return, which in turn, have to be presented to the user. Due to the nature of these kind of responses, handling them all in a single place would be ideal. 

Unfortunately, managing that in a React app has been harder than it should, with different completely approaches from app to app. In this article I'm going to present to you a way of handling your API errors once and for all in a centralized and easily extendable way, regardless of the state-management library (Redux, Apollo, etc.) that you are using. Moreover, the approach that we'll take can be re-used into all of your apps, regardless of whether you are implementing client or server-side rendering. So without further ado, let's dig straight in.

For the purposes of this article, I'll assume the presence of a RESTful API with the usual HTTP error status codes, but similar concepts apply to a GraphQL and any other API. I'll also assume the use of 

 , but the exact same concepts apply for 

Let's say we want to write a small app that's going to have 2 pages. The first page is going to show us a list of dog breeds. When we click on a breed, we'll be redirected to this breed's page, which will display a random photo of a dog of that breed. The app would look like this (don't worry too much about the code or the UI, since it's outside the scope of this article) :

import React from 'react';
import { BrowserRouter, Route, useParams, Link } from "react-router-dom";
import DogPage from "./DogPage";
import IndexPage from "./IndexPage";

// A page that shows us a list of dog breeds to select from
const breeds = ["husky", "akita", "pitbull"];
const IndexPage = () => {
  return (
    <div>
      <h1>View some nice pictures of a dog breed</h1>
      <ul>
        {breeds.map(breed => (
          <li key={breed}>
            <Link to={`/dogs/${breed}/`}>{breed}</Link>
          </li>
        ))}
      </ul>
    </div>
  );
};

// A page that given a dog breed, will display a random image of 
// the dog. The breed is passed as a URL parameter
const DogPage = () => {
  const { breed } = useParams();
  const [imageSrc, setimageSrc] = React.useState();

  React.useEffect(() => {
    fetch(`https://dog.ceo/api/breed/${breed}/images/random`)
      .then(data => data.json())
      .then(data => setimageSrc(data.message));
  }, [breed]);

  return (
    <div>
      <div>
        <Link to="/">back</Link>
      </div>
      {!imageSrc && <p>Loading...</p>}
      {imageSrc && <img alt={`A nice ${breed}`} src={imageSrc} height={200} />}
    </div>
  );
}


// Our App component that binds all 
const App = () => {
  return (
    <BrowserRouter>
      <Route exact path="/" component={IndexPage} />
      <Route exact path="/dogs/:breed/" component={DogPage} />
    </BrowserRouter>
  );
}

Our app works, but we haven't handled the 404 case yet. When the users visit a page that doesn't exist, we want to show them our very own 404 page with the text "Four:oh:four". This page should be shown in the following two scenarios:

The first case is easy to handle. Like most tutorials out there recommend, we'll just add a "catch-all" route as the 

 of our app and we will wrap all of our routes with react-router's 

 component. This would look something like this:

import React from 'react';
import { BrowserRouter, Route } from "react-router-dom";
import DogPage from "./DogPage";
import IndexPage from "./IndexPage";

// Our custom 404 component (normally implemented in ./Page404.jsx)
const Page404 = () => <h1>Four:oh:four</h1>

// Our App component from the previous example
// Our App component that binds all 
const App = () => {
  return (
    <BrowserRouter>
      <Switch>
      	<Route exact path="/" component={IndexPage} />
      	<Route exact path="/dogs/:breed/" component={DogPage} />
        <Route component={Page404} />
      </Switch>
    </BrowserRouter>
  );
}

Now whenever the user types in a URL other than 

, they will be redirected to the 404 page.

The second case is a bit harder to handle because it relies on our API. We don't know ahead of time, whether the breed that the user has entered as a URL parameter is valid or not, since we don't know all the breeds that exist in the world (or at least let's suppose that we don't). In order to show the 404 page, we have to wait for the server to respond and react (no pun intended) to the status that we got back. Modifying the 

 component, that would look something like that:

import React from "react";
import { useParams, Link } from "react-router-dom";
import Page404 from "./Page404";

const DogPage = () => {
  const { breed } = useParams();
  const [imageSrc, setimageSrc] = React.useState();
  const [httpStatusCode, setHttpStatusCode] = React.useState();

  React.useEffect(() => {
    fetch(`https://dog.ceo/api/breed/${breed}/images/random`)
      .then(data => data.json())
      .then(data => {
        setHttpStatusCode(data.code)
        if (data.status === 'success') {
          setimageSrc(data.message)
        }
      });
  }, [breed]);

  if (httpStatusCode === 404) {
    return <Page404 />
  }

  return (
    <div>
      <div>
        <Link to="/">back</Link>
      </div>
      {!imageSrc && <p>Loading...</p>}
      {imageSrc && <img alt={`A nice ${breed}`} src={imageSrc} height={200} />}
    </div>
  );
}

By storing the response code we can now react to its value and render different components. In the example above, if the status code was 404, we simply rendered the 404 page. This approach can work, but if you've used it before I can guarantee that you've had problems. To sum them up for you:

The easiest & most common thing people do, is simply redirect users to a 

 is rendered. This can work, but then the users lose context of where they are. They see a 404 page, but the URL that they have originally accessed has changed, so they don't know "which thing was not found" when they see a 404. What we want is a solution where the 404 page can be shown while the original url that they have accessed remains pristine.

The first approach that we are going to take, is to use a re-usable custom hook to avoid having to re-write the handling of the API status code into every component. This hook (in a very basic implementation) would look something like this:

import React from 'react';

const useQuery = ({ url }) => {
  const [statusCode, setStatusCode] = React.useState();
  const [apiData, setApiData] = React.useState();
  
  React.useEffect(() => {
    fetch(url)
      .then(data => data.json())
      .then(({ code, status, ...apiData }) => {
        setStatusCode(code)
        setApiData(apiData);
      });
  }, [url]);
  
  return { data: apiData, statusCode }
}

import React from "react";
import { get } from 'lodash';
import { useParams, Link } from "react-router-dom";
import useQuery from './useQuery';
import Page404 from "./Page404";

const DogPage = () => {
  const { breed } = useParams();
  const { data, statusCode } = useQuery({ 
    url: `https://dog.ceo/api/breed/${breed}/images/random`
  });

  if (statusCode === 404) {
    return <Page404 />
  }

  const imageSrc = get(data, "message");
  return (
    <div>
      <div>
        <Link to="/">back</Link>
      </div>
      {!imageSrc && <p>Loading...</p>}
      {imageSrc && <img alt={`A nice ${breed}`} src={imageSrc} height={200} />}
    </div>
  );
}

This solved our repetitive logic when it comes to handling the status code, but it didn't help a lot with the repetitive logic of rendering the error page according to the status code. This still needs to be implemented in each component individually. In addition, hooks are not usable in class-based components, so if you have an older codebase, that might pose a problem.

In order to allow for compatibility with class-based components and to reduce even further the amount of repetitive code, a render-props component can be helpful. Thus, using the 

 hook that we created before, we can now create the following simplified version of a render-prop component:

import React from 'react';
import Page404 from './Page404';

const Query = ({ url }) => {
  const { data, statusCode } = useQuery({ url });
  
  if (statusCode === 404) {
    return <Page404 />
  }
  
  // ... more HTTP codes handled here
  
  return children({ data });
}

import React from "react";
import { get } from 'lodash';
import Query from './Query';

const DogPage = () => {
  const { breed } = useParams();
  return (
    <Query url={`https://dog.ceo/api/breed/${breed}/images/random`}>
      {({ data }) => {
        const imageSrc = get(data, "message");
        return (
          <div>
            <div>
              <Link to="/">back</Link>
            </div>
            {!imageSrc && <p>Loading...</p>}
            {imageSrc && <img alt={`A nice ${breed}`} src={imageSrc} height={200} />}
          </div>
        )
      }}
    </Query>
  );
}

Now this solution allows us to remove any repetitive logic, handle any HTTP error code, have compatibility with class-based components and overall have clean code. The only thing we haven't solved yet though, is how can we make sure that the 

. To recap, the 404 page is rendered in place of our DogPage component, but what happens if the DogPage is not a top-level component but has lots of other ancestors? Then the 404 page will be rendered as part of the entire UI, alongside other components.

To combat the last issue, our only option is to render the 404 page before any other page has the chance to render. For that we need some sort of state management library that will allow components lower down the component tree to notify a top-level component that it should show an error page (404, 403, 500, etc.). For that we can use any library, but let's go with the baked-in Context API. 

What we need is a component that will make sure to render the proper error page based on the status code and will expose a way for any component to trigger this behavior (the showing of the error page). To implement it, we are gonna start by creating a high-level component that will expose the needed behavior via context. That might look something along the lines of this:

import React from 'react';
import { useHistory } from 'react-router-dom';


// A context will be the way that we allow components lower down 
// the tree to trigger the display of an error page
const ErrorStatusContext = React.createContext();

// The top level component that will wrap our app's core features
const ErrorHandler = ({ children }) => {
  const history = useHistory();
  const [errorStatusCode, setErrorStatusCode ] = React.useState();
  
  // Make sure to "remove" this status code whenever the user 
  // navigates to a new URL. If we didn't do that, then the user
  // would be "trapped" into error pages forever
  React.useEffect(() => {
    // Listen for changes to the current location.
    const unlisten = history.listen(() => setErrorStatusCode(undefined));
    // cleanup the listener on unmount
    return unlisten;
  }, [])
  
  // This is what the component will render. If it has an 
  // errorStatusCode that matches an API error, it will only render
  // an error page. If there is no error status, then it will render
  // the children as normal
  const renderContent = () => {
    if (errorStatusCode === 404) {
      return <Page404 />
    }

    // ... more HTTP codes handled here

    return children;
  }
  
  // We wrap it in a useMemo for performance reasons. More here:
  // https://kentcdodds.com/blog/how-to-optimize-your-context-value/
  const contextPayload = React.useMemo(
    () => ({ setErrorStatusCode }), 
    [setErrorStatusCode]
  );
  
  // We expose the context's value down to our components, while
  // also making sure to render the proper content to the screen 
  return (
    <ErrorStatusContext.Provider value={contextPayload}>
      {renderContent()}
    </ErrorStatusContext.Provider>
  )
}

// A custom hook to quickly read the context's value. It's
// only here to allow quick imports
const useErrorStatus = () => React.useContext(ErrorStatusContext);

This component is a tiny bit complex, so please make sure to read the inline comments for more clarity. 

To use this component, we are going to wrap our core logic with it like so:

import React from 'react';
import React from 'react';
import { BrowserRouter, Route } from "react-router-dom";
import DogPage from "./DogPage";
import IndexPage from "./IndexPage";
import Page404 from './Page404';

const App = () => {
  return (
    <BrowserRouter>
      <ErrorHandler>
        <Switch>
          <Route exact path="/" component={IndexPage} />
          <Route exact path="/dogs/:breed/" component={DogPage} />
          <Route component={Page404} />
        </Switch>
      </ErrorHandler>
    </BrowserRouter>
  );
}

 hook to automatically "trigger" an error page display whenever a bad status code is returned. That would mean that the 

 is no longer needed in our local state, since it's not managed by the 

. All we need is to fire an action to set the error status code.

import { useErrorStatus } from './ErrorHandler';

const useQuery = ({ url }) => {
  const { setErrorStatusCode } = useErrorStatus();
  const [apiData, setApiData] = React.useState();
  
  React.useEffect(() => {
    fetch(url)
      .then(data => data.json())
      .then(({ code, status, ...apiData }) => {
        if (code > 400) {
          setErrorStatusCode(400)
        } else {
          setApiData(apiData); 
        }
      });
  }, [url]);
  
  return { data: apiData }
}

Finally, now that we have error handling in our 

 component, we now no longer need to react to error statuses in our components. Thus, our 

 component can take its final form, by stripping away any status checks:

import React from "react";
import { useParams, Link } from "react-router-dom";
import { get } from 'lodash';
import useQuery from "./useQuery";

const DogPage = () => {
  const { breed } = useParams();
  const { data } = useQuery({ 
    url: `https://dog.ceo/api/breed/${breed}/images/random`
  });

  const imageSrc = get(data, "message");
  return (
    <div>
      <div>
        <Link to="/">back</Link>
      </div>
      {!imageSrc && <p>Loading...</p>}
      {imageSrc && <img alt={`A nice ${breed}`} src={imageSrc} height={200} />}
    </div>
  );
};

So there you have it, a way to centralize error handling, through an easy (hooks), automated (no need to handle it in any future component) and scalable way (since you can handle any error you need in 

The above solution works well, but it's not re-usable across all React projects. The thing is that the above approach works well when the fetching stays within the boundaries of React, but it becomes tedious when API calls are made in the redux world. How would you trigger the 

 from a redux  thunk? You simply can't. What you'd need to do is trigger an action that would change the redux state and have 

 read from the redux state, but that would involve a lot of boilerplate code. Imagine the same in Apollo. That would involve using 

 and dispatching a mutation just for the freaking status code update.

With this in mind, let's take a step back and think what exactly are we trying to achieve here. We want to tie URLs to status codes and decide what to render based on the value of the code that's attached to them. Well, it turns out this is extremely easy by utilizing a browser native feature that not too many of us use. 

On browser's native history API, each location can have a state key attached to it which can store anything we want. Why not utilize it to store the 

 there instead of a local state? The bonus to this approach is that:

import React from 'react';
import { useLocation } from 'react-router-dom';
import { get } from 'lodash';
import Page404 from './Page404';

const ErrorHandler = ({ children }) => {
  const location = useLocation();

  switch (get(location.state, 'errorStatusCode')) {
    case 404:
      return <Page404 />;
    
    // ... cases for other types of errors
      
    default:
      return children
  }
};

and any module in our system (regardless of whether it lives within React or not) can attach an  error code to a page by taking the current location, adding a state to it and replacing the current history entry . To showcase that, we will modify our 

import React from 'react';
import { useHistory } from 'react-router-dom';

const useQuery = ({ url }) => {
  const history = useHistory();
  const [apiData, setApiData] = React.useState();
  
  React.useEffect(() => {
    fetch(url)
      .then(data => data.json())
      .then(({ code, status, ...apiData }) => {
        if (code > 400) {
          history.replace(history.location.pathname, { 
            errorStatusCode: code 
          });
        } else {
          setApiData(apiData);
        }
      });
  }, [url]);
  
  return { data: apiData }
}

The benefit of this solution is that the 

 hook is not even aware about the presence of the 

 component. All it does is modify the location as a side-effect, in order to add a certain state to the current history entry. That means that the 

 are not inter-dependent, so you can switch any of them out without any issues. 

 hook you now have a centralized API error handling module. It should be mentioned, that If you are using a state management library, chances are you

 hook. Instead, you will have to manually trigger the 

 as part of your HTTP fetching logic, which differs from library to library. Let's see how you would tackle that in some of the most popular ones:

To implement this solution in redux, you'll need to access your history. There are multiple ways of doing it, either by passing the history as a parameter to the 

 function and creating a middleware or by simply utilizing 

 which exposes an action creator to modify your history directly. Simply fire this action with the correct params and you are good to go! The documentation has you more than covered on how can this be done.

To handle that in the Apollo client you'll need to utilize 

 and create an error link that will have access to the history in order to call 

. The easiest way to do that, is to create an instance of history (through the 

) and utilize it directly within the link. The same instance would need to be passed to the 

 component. If you don't want to do that, another option would be to read the history from the 

 hook, pass it as a parameter to the client (which would need to be created inside a react component) and then forward it to the error link. The latter is an approach you should consider only if you want to depend on the Router to provide a history instance, which would allow you to keep the same Apollo client for both your production and testing environment (due to dependency injection).

Although a lot of code that we've written in this article was not used at the end, it was necessary to showcase the problems with a lot of approaches I've seen out there. The goal of this article was to give you a nice way to handle API errors once and for all in all of your React apps. You can now forget about context, state, re-renders, hooks and everything. All you'll ever need again to handle your API errors is a top-level component that reads the current location's state and reacts accordingly, coupled with any sort of central "api module" that can modify the history. This solution is nice not only because it doesn't enforce component coupling, but because it's so abstract & generic that can easily be ported into any framework. So far this has played nicely in most of my apps and I'm really happy with it, but I'm curious to see what you think. The code for the final solution can be found 

Please feel free to ask any questions or recommend even better ways of approaching this issue; I'd be glad to hear about them. 

! If you liked this, consider following me on twitter or  

AUTHOR

Aggelos Arvanitakis

 are not inter-dependent, so you can switch any of them out without any issues. In addition, you can add 

. For example, you can add a list of whitelisted queries whose 404 error you want to ignore  or a strategy on handling multiple simultaneous errors. Each app differs on its requirements, so this particular logic is tied to your business. 

Learn

The newline Guide to Building Your First GraphQL Server with Node and TypeScript

Teach

Amelia Wattenberger

Author of Fullstack D3

Community

Centralizing API error handling in React apps

Responses (0)

Masterclasses

Tutorials

Fullstack React with TypeScript