Customize Error Pages

Error pages: the pages you never hope your customers see but know they sometimes do. The type of errors returned to the users typically correlate to HTTP status codes, with the most notorious being the 404 (page not found) error.

As an online retailer, your goal is to convert visitors into paying customers. A user seeing an error page interrupts that process, it jars them, it means they see something they didn't intend to. However, this doesn't have to be a wholly negative experience. As part of SCA, we include ways for you to change the content of these error pages and I'll take you through them. I'll also be dishing out some advice on how to optimize these pages so that people have, well, the least unsatisfactory experience possible.

What's Included

Let's take a look at what's included in SCA. We have a module dedicated to error management, which is located under Modules > suitecommerce > ErrorManagement. Under the Templates directory, you'll extrapolate that we have templates for the following cases:

  • Expired link — the user clicked a password reset link that has already been used, or it's past its usable time window
  • Forbidden — the user is served a 403 status code (i.e., they don't have permission to perform their previous action)
  • Internal error — the user is served a 500 status code (i.e., something went wrong on the server)
  • Logged out — the user tried to perform an action which requires them to be logged in for (i.e., they were logged in but have since either been logged out, their session expired, or logged in on another device)
  • Page not found — the user attempted to visit a page that does not exist

If you look at the views for each of these, you will see that they are displayed in various different ways. One invokes the global messaging module, whereas the others display a page with the error message on it.

In truth, users are very unlikely to see the majority of these errors. We put protections in place to ensure that users are routed to the correct places. For example, to test the logged out error message, you may think you could log in to your account, duplicate the tab, log out of the session in the other tab, and then try to access an order. You'll note, though, that instead of showing an error page, you're instead directed to the login page.

Indeed, the most likely page your users will see is the error 404 page. On ecommerce sites, these can arise for a number of reasons including:

  1. Broken links
  2. Incorrectly typed URL
  3. Products that are no longer available

With that in mind, let's look at the ways of improving the 404 page.

Error 404

We provide a functional default with SCA — one, however, that is far from optimal.

There's a plethora of advice on the internet about what makes a good 404 page and some in our static content documentation, which says:

A good error page explains the problem in simple language, apologizes for the inconvenience, and offers an action to take. This ensures no dead ends.

If you take a look at your own 404 pages, you'll probably note how similar it is to our defaults and how it doesn't follow this philosophy. So let's think about this a little bit more.

Get on Message

Anyone who's used the internet for even a little bit will have likely seen a 404 page. However, we cannot assume that people truly understand what they mean and, given you're running a online shop, there is additional context that you need to account for.

Thus, if I was running an ecommerce site I'd probably write something along the lines of:

Page Not Found

Sorry, we couldn't find the page you were looking for.

This is usually because of either:

  • A mistyped address, or
  • An out-of-date link.

If you typed the URL, check for spelling mistakes.

If you tried to reach a product, use the search box to search for it.

Finally, you can simply return to the homepage.

As you can see, we're fulfilling the three rules for a good error page:

  1. Explain the problem in simple language — "we couldn't find the page you were looking for". This is what went wrong. It may be obvious to experienced users, but this says clearly what the problem is.
  2. Apologize for the inconvenience — we've said sorry. Sometimes it's the hardest word to say, but putting it on your error page is easy (so do it).
  3. Offer an action to take — we've offered a few, in fact. After all, there are numerous reasons why a person may have found themselves in this situation. We've given them advice on checking the URL, told them to try the search box if it's a product, and also, finally, simply to return to the homepage. Nice, clear instructions.

By improving the messaging around this, you can transform the experience. This is no longer a dead end, but rather a bump in the road towards a conversion.

Something Special

Many sites use their 404 as an expression of their brand's voice and sense of humor. As an online retailer you may not want to go down that route. After all, no one is going to complain about a functional, apologetic 404 page but you may annoy people if you're too cutesy (e.g., "Oops! Something went wrong!") or borderline obnoxious (e.g., an image of the frowny emoji). After all, your user may be very frustrated by having ended up where they are and want a supportive (not a blasé) attitude.

However, you could certainly follow what a number of retailers do, which is to add an imagery. After all, when I put my new text into my template I got the following, devoid of styling:

The page doesn't have to be as beautifully crafted as some of your other pages, but you can put a little bit of effort in!

I've noticed a number of online retailers using imagery to enhance the look of their page. It can be something simple, as long as it enhances the plain, drab page. Yes, your user ended up where you didn't want them to, but it doesn't mean it has to look different from the rest of the site. So, for example, I went with the following for my site:

Other Error Pages

As mentioned, the 404 page is probably the page you expect customers to see the most often, albeit rarely. However, there are other error pages and testing them is a lot less straightforward. After all, if you want to test the server not finding your page, you can just type a junk URL in and it'll be served. However, testing the internal server page would require an actual internal server error, and we don't want to force that.

Gratefully, the power of Backbone allows us to write some code that simulates these errors. Using a simple router, we can list the views of the error pages as dependencies and then create URL paths that serves them up. In this sense, you can create an 'error service' module, that let's you test your error pages without actually creating the errors.

I'll include the full code at the end but in the meantime, here's what you need to know: first, create a new custom module (directory, entry point file, ns.package.json, updates to distro.json, etc.). After that you'll need to create a router file. For the purposes of my module, I'm calling it ErrorService.Router.js. In it, put the following:

  , 'ErrorManagement.ForbiddenError.View'
  , 'ErrorManagement.InternalError.View'
  , 'ErrorManagement.PageNotFound.View'
, function (
  , ForbiddenView
  , InternalErrorView
  , PageNotFoundView
  return Backbone.Router.extend({

    initialize: function(application) {
      this.application = application;

    routes: {
      'error/forbidden': 'errorForbidden'
    , 'error/internal': 'errorInternal'
    , 'error/notfound': 'errorNotFound'

    errorForbidden: function() {
      var view = new ForbiddenView({application: this.application});
      console.warn('Simulated Error 403');

    errorInternal: function() {
      var view = new InternalErrorView({application: this.application});
      console.warn('Simulated Error 500');

    errorNotFound: function() {
      var view = new PageNotFoundView({application: this.application});
      console.warn('Simulated Error 404');

Pretty simple stuff: routes in the form of error/[error type] that point to functions that serve up the views for each of the errors we want to test. I've only included three (and the 404 is somewhat redundant) but you get the idea: you can add other routes and functions in a similar manner for the other errors. Your entry point file only needs to return the router, so there's nothing complicated there. Then, after (re)starting your local server you'll be able to visit these error pages and see what they're like.

Personally, I'll also use this module as a handy place to save all of my customized error pages. For example, the template I'm using to override the 404 page (and its accompanying Sass and imagery) is stored in this module.

Of course, this only simulates the errors by loading the relevant error pages. It is possible to write an actual error service that simulates actual status codes from the server. I'll include the code for that service in the zip file below. This is useful, I guess, if you actually want to see what happens. It'll require some tinkering on your part to make it fit into the module (so in this sense, it's only for advanced users).


Take time to improve your error pages. Good error pages apologize to the user, inform them of what went wrong, and then gives them a way out. Although I haven't got into a lot of details surrounding design ideas for them, there are numerous examples on the web. Think about how it fits in with the rest of your site, how you can use your site's tone to convey the message appropriately.

Focus on your 404 page, as that is the page the user is most likely to see. However, keep in mind the other error pages. Use testing to simulate what these pages will look like, should a user ever see them.

I have compressed the ErrorService module for you to download here: Note that this is provided 'as is' and we offer no warranty or guarantees about its efficacy.