Adding Custom Error Pages

Introduction

In this blog post, we’ll be adding custom error pages for the three most common HTTP errors: 404 (Not Found), 403 (Forbidden), and 410 (Gone).

Typically when you request a web page, the application will return the HTTP response status code of 200 (OK), which indicates that the HTTP request was successfully processed by the server. If you look at some of the unit tests that have been generated in this Flask tutorial, there are a number of checks for a HTTP response status code of 200 (OK) to make sure a specific page is returned properly.

However, if you request a web page that does not exist, the HTTP response status code returned will be 404 (Not Found). This can occur if you are trying to access a web page that does not exist or if you accidentally typed in an incorrect site (for example with our application, if you type localhost:5000/log_in instead of localhost:5000/login). A similar result will occur if you attempt to access a web page that you don’t have permission to access. For example, if you are logged in as a standard ‘user’ but attempt to access the administrative page that we created in the Administrative Page for Viewing Users blog post.

Flask provides a very convenient function, abort(), that aborts a request with an HTTP error and provides a simple page displaying the error. However, there is a way to create custom error pages to handle specific HTTP error codes, which we’ll be implementing in this blog post.

Setup

Before starting to make any changes for this user action, let’s create a new feature branch:

There are no new modules to install for this blog post.

Templates for the Custom Error Pages

The first step in creating the custom error pages is to define separate templates (in …/projects/templates) for each error code. We’ll be focusing on three of the more common error code (404, 403, and 410) so we’ll need to create templates for each error code.

Here is the template for the most common error message, 404 (Not Found), as defined in …/project/templates/404.html:

This template provides a more custom feel than the typical error message that you see from most websites, as it still has the overall feel of the application with the Navigation Bar and footer still displayed via the inclusion of layout.html. Additionally, this error page provides a link back to the main page of the website to allow the user to get to a known state

The template for the 403 (Forbidden) error is very similar (as defined in …/projects/templates/403.html):

Finally, the template for the 410 (Gone) error is defined in …/projects/templates/410.html:

Registering the Error Handlers

We just created the custom templates for handling the 404 (Not Found), 403 (Forbidden), and 410 (Gone) error codes, but now we need to register the error handlers to properly render these templates. The best place to register the error handlers is in the top-level __init__.py file. Add the following lines to …/project/__init__.py to register the error handlers for these specific error codes:

Each of these blocks of code have a decorator (@app.errorhandler()) with a specific HTTP response status code to process. For each of the specified error codes, as the associated template is rendered and the error code is also returned as Flask does not automatically set the error code for you when using this decorator.

Let’s go ahead and try out some of these error codes… fire up the development server:

Try navigating to localhost:5000/hello and you should see the page associated with the 404 (Not Found) error code:

Now try logging in as a standard ‘user’ (ie. not an ‘admin’) and navigate to localhost:5000/admin_view_users. You should see the page associated with the 403 (Forbidden) error code:

Checking In Our Changes

Now that we’ve completed implementing the custom error pages, it’s time to check in the changes into the git repository:

$ git add .
$ git status
$ git commit -m “Added custom error pages for 404, 403, and 410 error codes”
$ git checkout master
$ git merge add_custom_error_pages
$ git push -u origin master

Conclusion

This blog post showed how to implement custom pages for specific HTTP response status codes. The three error codes that were included are three of the more common error codes: 404 (Not Found), 403 (Forbidden), and 410 (Gone).

While these error pages are not necessary for your application, they do provide an improved user experience as there is more than just a blank error message and there are multiple ways for a user to continue navigating within your application.

The files associated with this blog post can be found using the ‘v2.0’ tag in GitLab.