Choose Your Battles? I Say Choose Your Error Codes

Once delivering your web application to the end-user, you want to make sure that the client receives the best user experience, You don’t want dead ends in your app, every flow, every page has its own starting-point and ending-point.

So you have a plan how to create your website, you listed all the 3rd parties that you are going to use and you setup your backend to deliver the data for your web application and now the story begins.

When we design a well-planned web application, we want to make things as simple as possible to make our life easier when we develop new features or maintaining our business and in such web applications we have a single place that we are using to execute our REST calls. Why do we want to do it? because in this place we are adding special headers (if needed) for authentication, we can log activities for monitoring and analytics purposes and we can control our backend errors.

Photo by Brett Jordan on Unsplash

I got the error code, What’s next?

So we have an error code from a REST that we just executed, what’s now? we have several ways to handle it

1. Notification — display a friendly notification to the user that something went wrong with dedicated message.
2. Message — display a message next to the related business area, it can be error with validation from backend.
3. Dedicated Page — redirect the user to a dedicated page, for cases that you don’t have special handling, It can even be an internal error in your server — unplanned activity.

The worst thing that can be is that your user gets an error and sees a blank page.

Let’s get technical

If you reach here, you may say, alright, my error codes are properly handled, special messages and notifications are shown, and I even have a dedicated error page so I am covered. All is fine. Yet, Which approach do you choose? In the following, I’m going to show you an approach which I find convenient and the most recommended.

One of the features in Harmony is the error-handler, it is a stand-alone feature that is being used all over the application, It lives on the root component and enables the developer to use a decorator for special cases such as a handler for component level errors.

So how it is structured?

We have the main container, the one that is connected to the application state, that container being used in the root component.

Alongside that container, we need to define the reducer to a process that dispatches error actions that are being thrown in the system.

To be able to dispatch those error actions we will create a generic function to be used, This function receives the response and processes it for further handling.

How does it work?

So we have the function that handles the response in case of error failures, as well as the reducer. Now we need the configuration so the function can proceed further and tells what to do, e.g. what is the behaviour when calling to API X and receiving status code Y? Let’s see.

In the “dispatchErrorHandler” we create the key from the response error code and the status code, As you can see, the path is defined for the error code in our response, it can be data.errorCode and when we combine it with the status code we get the key for the error handler configuration and this can be used to know how to handle this error.

You may ask, who calls the dispatchErrorHandler, as I explained previously, we want to create as many common components as we can, For example a single place that all the API calls are going through.

In this place, we can invoke the global spinner in our website, we can set special headers, such as authentication headers and we can catch the API failures and move them to our dispatchErrorHandler. Let’s see the following debug session.

In the same way we can modify the configuration and the web app will behave differently, We can choose to handle the same status code from the same API as modal by just changing the configuration.

Photo by Vadim Sherbakov on Unsplash

When we prepare the right design, everything is much simpler, If you reach this point, I assume that you understand how easily we can change the configuration and change the behaviour of our website when it comes to handling the errors, What if you have a company that creates websites for customers and one of their requirements is to change the behaviour of the errors? the same configuration that I showed you can be fetched from an external resource and with this approach you have an independent mechanism for managing errors in your web application.

What if we want to take our error handling to the next level? maybe to show an error only for specific component in our screen?

Photo by Emile Guillemot on Unsplash

Decorator

A Decorator is a special kind of declaration that can be attached to a class declaration, method, accessor, property, or parameter. Decorators use the form @expression, where expression must evaluate to a function that will be called at runtime with information about the decorated declaration. — https://www.typescriptlang.org/docs/handbook/decorators.html

One of the exposed functionalities in the error handler that created in Harmony is the “withError decorator”, This decorator provides the ability to replace the annotated component with pre-defined error from the configuration shown previously.

So how it is working? we are wrapping our component with a decorator that is connected to the store, the same state that we handle in the global error handler component being used here, with this approach we know by the configuration what to show.

Refer to the following configuration

What if we do not configure any error codes in the error handler configuration? Remember what I have said: the worst thing that can happen is that the user gets an error and he sees a blank screen.

Would you like to share with us how you handle your errors? need some help? do not hesitate to contact us..

Wrapping Up

This article should give you a different point of view on how to handle error codes and how to utilise them for providing better user experience to our end-users.

Who am I?

I am Ofir Attia, a Web developer, focusing on design and architecture. Currently working at Amdocs as Software Architect.

Contributing

Special thanks to my co-worker Refael Oknin, Refael and I develop open-source libraries together for the past 2 years.

the Error Handler feature comes as part of the harmony-boilerplate that we developed.

Want to know more about Harmony? read the following article.