Write actionable errors

When we think of Chat app errors, some of us may think of HAL 9000's infamous error message from the movie 2001: A Space Odyssey: "I'm sorry, Dave. I'm afraid I can't do that." Entertaining cinema; frustrating Chat app interaction. Instead, HAL should have responded with an actionable error message.

An actionable error message tells the user how to proceed towards their goal; hopefully without encountering another error, like a missing space helmet.

Error message structure

An actionable error message is structured like this:

• What went wrong. Saying why the Chat app can't complete a request helps the user resolve the issue. Explaining why an error occurred builds trust.
• How the user can proceed toward their goal. It's never enough to just say what went wrong. Tell users how they can move past the error and complete their goal.
• How to get help. If the user is still stuck, tell them how they can get more help. This could be a /help command or a link to documentation for your Chat app.

Example error messages

Let's look at some example error messages. Each of these error messages is written as an actionable error and as an inactionable error.

Example error message: incorrect date format

The user entered a date format incorrectly. They wrote November 19, 2021, but the app expects 2021-11-19.

Here's an actionable and an inactionable version of the error message that the app responds with:

Actionable error

The app responds with a good, actionable error message:

I don't recognize the date format you entered. Write dates as yyyy-mm-dd, for example: 2000-01-31. For help, type /help.

This error message is actionable because it:

• Says what went wrong. The app doesn't recognize the date format.
• Explains how to fix the error by telling the user the expected date format. Because the date format is technical, so the app gives an example date that helps people understand what to write.
• Offers more help with a /help command. If users are still stuck, they know how to learn more.

Inactionable error

The app responds with an unhelpful, inactionable error message:

Enter the correct date format.

This error message is inactionable because it doesn't:

• Say that it did not schedule the meeting. The user might be hesitant to re-schedule the meeting, or they might assume that the meeting was scheduled.
• Tell users how to format the date. Instead of assuming that users know how to format the date, it should say that it's expecting the date format yyyy-mm-dd.
• Offer more help. When users are stuck and don't know how to proceed, they might stop messaging the app.

Now think about your error messages. Are they actionable? If a user who had never worked with Chat apps before reads your error messages, can they proceed and achieve their goal?

Try it out

Now that you know how to write actionable errors, can you identify which of these errors is actionable?

Scenario:

Scheduler app creates calendar events when users message the app with the keyword schedule. In order to create a calendar event, Scheduler requires user authentication. If a user hasn't authenticated, then the Scheduler app responds with an error message.

Which error message is actionable?

Before I can schedule the meeting, you need to log in by typing /login. To learn more, type /help.

This error message is actionable because it says:

• What went wrong: the app requires authentication.
• How to proceed: type /login to authenticate.
• How to get help: if the user wants more information, they can type /help.

You need to authenticate.

This error message is inactionable because it does not say how to authenticate.

Sign in.

This error message is inactionable does not say how to sign in, and it implies that the user is signed out instead of clearly saying so, which is confusing.

Can't schedule meeting.

This error message is inactionable because it doesn't tell the user why the meeting can't be scheduled or how the user can proceed. No help is provided.