Bits | Freelancer Bits

Foundations

Error Handling Guidelines

We need to keep error messages consistent and user-friendly. When handling a new error case, the following guidelines should be followed.

"Established wisdom holds that good error messages are polite, precise, and constructive. The Web brings a few new guidelines: Make error messages clearly visible, reduce the work required to fix the problem, and educate users along the way." ― Nielsen Norman Group, Error Message Guidelines

Design Principles

First and foremost, if a problem occurs, it should fail gracefully if possible. This means that the product should not be brittle. Functions should be fail-safed by including fall back actions and retries. Displaying errors to the user should only happen in exceptional cases where the prior actions repeatedly fail.

Purpose

Error messages should be purposeful, achieving the following goals:

Awareness

Show the user an error occurred and why

Action

Give the user actions to take to rectify the issue. We want them to be able to fix the issue themselves if possible.

Education

Educate users if they made a mistake so it doesn’t happen again.

User Experience

In general, we want to enhance UX where possible. This includes:

Preserving the user’s work

Reducing the effort involved in rectifying the issue

Ensuring visibility of the error if it is not whole-page

Providing links to support, FAQ and common areas of the site

Providing a search field linked to site’s search engine if feasible

Error message copy

A human description is a detailed description of what happened and why. It should be:

Explicit

Needs to include what went wrong as well as reasons why

Good

You cannot purchase the exam because it seems you do not have enough funds

Bad

Not enough funds

Polite

Must not put blame on the user or imply they are wrong

Good

The page you are looking for could not be found. This may be because...

Bad

You tried to access an illegal page

Precise

Must be specific to the erroneous event that occurred

Good

Date of birth must be in the format DD-MM-YY

Bad

Syntax Error

A human action is an actionable item the user can take and should be:

Descriptive

Needs to be precise on what the user can do - use steps if necessary. Assume that the user has no idea what they are doing.

Good

Check that you have the necessary funds in your account by going into

Good

Deposit more funds into your account. Visit for more information on .

Good

Go back to the and attempt to buy the exam again

Good

If the problem persists visit our or

Bad

Deposit more funds into your account

Educational

We should take this time to educate the user on the process of how to perform the task(s) properly to reduce future occurrences. We can do this by providing steps as before or linking the user to an appropriate article.

Note that for every error, there should be more than one action that the user can take. Usually, there will be an action for contacting support and searching the knowledge base for more information. These guidelines should also be used when writing additional information that will be used by support.

Resources and References

How to Write a Perfect Error Message - UX Planet

How to implement errors in GAF