How To Implement Custom Error Responses in Express
Tags: javascript, programming, webdev
Published: 2022-08-22 20:57:30

### Learn why you may need custom error responses on 4xx errors, what a good custom format looks like, and how to apply it to your error responses in Express.

### <br>

The 4xx HTTP status codes may not be enough to describe the cause of the error to the client. For this reason, several companies introduced a custom error response format to provide the caller with everything they need to deal with the error. This is a great addition you can make to your backend application, especially considering that implementing it requires only a few lines of code. Let's see what you need to get started with error response customization for `401 Unauthorized` and `403 Forbidden` errors in Express.

## An Introduction to HTTP Error Status Codes

The HTTP status code is a code number returned by the server in response to a client's request. The many [HTTP status codes](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes) available can be grouped into the following five classes based on their number:

- `1xx`: [informational responses](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#information_responses)
- `2xx`: [successful responses](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#successful_responses)
- `3xx`: [redirection messages](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#redirection_messages) 
- `4xx`: [client error responses](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#client_error_responses)
- `5xx`: [server error responses](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#server_error_responses)

As you can see, there are only two categories of HTTP status codes that represent errors: `4xx` and `5xx`. 

The `4xx` class of HTTP status code refers to errors due to the client's request, for example, because of a malformed request. When it comes to `4xx` errors, the server should provide the client with additional info behind the error to prevent it from causing it again. 

The `5xx` class of HTTP status code refers to errors encountered by the server while processing the request. For security reasons, you should not provide the client with additional info about this type of error. This is because you do not want an attacker to understand how the server works based on what you returned to them.

Using the right HTTP error status codes is important to help the client understand what occurred. In fact, each `4xx` or `5xx` HTTP status code corresponds to a particular type of error. For example, the `400` status code should be used when the form of the client request is not as the API expects, while the `401` status code should be returned when the client provides no credentials or invalid credentials. However, with `4xx` errors, the HTTP status code alone may not be enough, and you should provide the client with more info. 

Let’s delve into why you might need to customize your HTTP error responses.

## Why Customize Error Responses?

Considering that `4xx` errors are caused by the client's request, not receiving enough info to understand why that request failed may be frustrating. Therefore, you need to customize error responses to provide the client with more details about the problem that occurred. This means returning additional data along with the HTTP error status code.

For example, imagine a situation where an API requires a numeric `customerId` parameter. Now, a client calls that API without the `customerId` parameter or using a non-numeric string. As a result, it will receive a generic `400 Bad Request` error from the server. As you can imagine, the default "Bad Request" message cannot help the caller understand how they should call the API. On the other hand, if the server returned a `400` HTTP status code response containing the "customerId required" or "customerId must be a number" message, the client could figure out how they need to call the API properly and avoid making the same mistake twice. Therefore, providing a detailed message on `4xx` errors helps end-users, and it is also why several companies with public APIs use custom error responses.

> Notice that customizing error responses represent a security concern. Although providing extra info in case of errors can be helpful, you should never return info that could jeopardize the security of your application. This is why you should consider customization on error responses only on `4xx` errors, which are all directly referable to the client. On the contrary, you should never provide additional info on your `5xx` error responses.

Now, let’s see an interesting format for your custom error responses.

## A Format for Your Error Responses

To get an idea of how to define a good custom error response format, you can have a look at what reputable companies with public APIs like Google, Apple, and Amazon do in case of errors. For example, this is what GitHub returns in case of a `401` error:


```json
{
   "message": "Requires authentication",
   "documentation_url": "https://docs.github.com/rest/reference/repos#create-an-organization-repository"
}
```

Returning a string message containing the error description is a common practice, but what is particularly insightful is the `documentation_url` field. This is a brilliant idea to provide the caller with pathways to solutions and not just report error messages. Also, if something changes, you do not have to update your error responses. What will be changing is the content of the documentation page used in the error response. In addition, returning a public link to the documentation does not pose a security problem by definition because anyone can already access the documentation.

Now, let’s see how to customize your error responses to follow this format in an Express server.

[Read more...](https://auth0.com/blog/how-to-implement-custom-error-responses-in-expressjs/?utm_source=content_synd&utm_medium=sc&utm_campaign=global_dist)