Fixing what’s broken: How to improve your in-product error messages
Resilient product UX depends on thoughtful feedback systems
When you set out to do something, there are signals that indicate if you’re on the right track. It could be a road sign that tells you which highway you’re on, or the texture of your pasta after it’s been boiling for 7 minutes. These signals let you know if you need to make adjustments to complete a task, like reaching a destination or making perfectly al-dente pasta.
In UX design, these signals are referred to as feedback. One of the most common types of feedback in an online experience is the error message. Error messages are the backbone of any product. They provide guidance, communicate the outcome of an action, and help users troubleshoot. Without feedback, users can feel uncertain, lost, and frustrated.
On the Shipping team at Shopify, we help merchants send orders out to their customers. It’s one of the only places in our product where merchants can purchase something — in this case, shipping labels. In transactional experiences, feedback is especially important. Our merchants are not just trying to complete a task — this task involves spending money. Not only does our feedback need to communicate if transactions are successful, but it also needs to guide merchants along the way and help them make informed purchases.
Guiding merchants means that we need to plan for error messages during early UX explorations. But because we move fast, we sometimes tackle error messages later in product development than we should. This was the problem we were facing — error messages that were confusing, repetitive, and poorly timed because they were created too late in product development.
In this post, I’ll walk you through how we’re improving our error messages using Polaris — Shopify’s style guide — as a foundation. By understanding our feedback types, defining a hierarchy, and creating guidelines, we’re restructuring existing patterns to strengthen the usability of our product.
Understand the current feedback system
Before we could begin improving messages, we had to understand what existed. To accomplish this, we put together an inventory.
Not to be mixed up with an audit, an inventory is a catalog of content that defines what currently exists. It’s not the place to write revisions or add notes. While an inventory will help with future content work — including information architecture, strategizing, and understanding systems— it starts as a source of truth for what you currently have.
To get our inventory going, we worked with a developer to get a list of all messages currently shown in a flow. These messages included errors, warnings, and neutral information (like new features), as outlined in Polaris.
From there, we classified the feedback using attributes. Attributes help you filter through content and see emerging patterns.
Attributes will be different depending on your product and the type of content, but here are the attributes we found to be useful:
- What type of feedback are we trying to communicate?
- Where on the page does it appear?
- At what loading state does it appear?
- What triggers this message?
- Can the user resolve it on their own?
Define a hierarchy
Once we had an idea of existing patterns we began to spot inconsistencies. At the root, most of the inconsistencies were due to a lack of hierarchy.
Hierarchies arrange pieces of information and help us understand their relationships to one another. Hierarchies exist all around us, from corporate hierarchies (manager > specialist > coordinator > intern) to botanical hierarchies (flower > leaf > sprout > seed). In most hierarchies, sub-categories refine the categories directly above them.
For our feedback hierarchy, we decided to classify errors based on their level of importance. To determine importance, we asked ourselves these questions:
- What is the consequence of the merchant ignoring this message?
- Does this message block the main call-to-action?
- What are we trying to tell merchants with this message?
Referring to Polaris, we started with a baseline hierarchy:
Level 1: Critical messages
These messages block merchants from completing the task.
- Example: “Total weight must be greater than 0.”
Level 2: Warning messages
These messages highlight information that the merchant should review.
- Example: “This address couldn’t be verified.”
Level 3: Informational messages
These messages share neutral feedback.
- Example: “You can now protect your packages with additional shipping insurance.”
Because there were nuances between messages within categories, we decided to get more granular and define new sub-types. These new sub-types helped us further prioritize messages.
Level 1: Critical messages
- Level 1.1: System errors
- Level 1.2: Account errors
- Level 1.3: Validation errors (incorrect or missing information)
Level 2: Warning messages
- Level 2.1: Verification warning (information may be incorrect)
Level 3: Informational message
- Level 3.1: Notifier (neutral feedback)
- Level 3.2: Feature (announcing a change or an update to our product)
With this newly defined hierarchy, we were able to spot redundant and poorly timed messages. As feedback guides users through tasks, it’s important to show the user what’s most important rather than expect them to parse through the information themselves.
Create guidelines
Now that we understood the current state and re-envisioned our hierarchy, we were ready to add the final touch — guidelines. Guidelines are important for two main reasons: they uphold consistency across a product and help teams grow. When something foundational within your product is re-worked, it’s important to consider what resources will exist for new team members.
Using a doc, we created guidelines for anyone at Shopify who needed to write critical, warning, or informational messages related to shipping. This audience didn’t only include our content strategists—designers and developers also write messages from time-to-time. With that in mind, our guidelines needed to be easy-to-understand and provide just the right amount of information.
Our guidelines for feedback focused on three areas: behavior, tone of voice, and controlled vocabulary.
Behavior
How different types of feedback appear to the user is determined by their behavior. To uphold the hierarchy, we needed to define how each type of message would behave.
Behavior is about how the user perceives the message:
- What color is the message?
- Where on the page is it located?
- Are there buttons or text links within the message?
- Is the message dismissible?
This perception affects the resulting action. If missing information is blocking the user from continuing, it wouldn’t make sense to use a neutral color like blue, nor would it make sense to place the message at the bottom of the page.
Here’s the behavior that we defined for each type of message:
Level 1: Critical messages
- Appears at page level or in the section where information is missing
- Blocks the primary CTA (call-to-action)
- Non-dismissible
- May include a button and/or a text link
Level 2: Warning messages
- Appears in the section where information needs to be reviewed
- Doesn’t block the primary CTA
- Non-dismissible
- May include a text link
Level 3: Informational message
- Appears at page level (new features) or in the section we’re providing neutral feedback for (notifier)
- Doesn’t block the primary CTA
- Dismissible
- May include a text link
Tone-of-voice
As we had defined new sub-types of messages, we chose to include brief guidelines on how each type of message should be written. We framed these tone-of-voice considerations from the merchant’s perspective. While the behavior of each type of message could help the merchant understand the level of importance, the tone could as well.
For each type of message, we defined an empathy anchor — an empathetic summary of the context in which our merchant would see this message. This helped us ground our thinking in the merchant’s current emotional state.
For example, the empathy anchor for a critical message might sound something like this:
Critical errors can be scary. They can slow down and frustrate merchants. We should help the merchant resolve them with confidence.
On the flip side, the empathy anchor for an informational message might sound like this:
Informational messages should be subtle and not get in our merchant’s way. This is a “nice-to-know” piece of information that doesn’t require action.
In terms of tone-of-voice guidelines, we stuck to what’s defined in our Polaris error message guidelines. Some best practices for writing messages include:
- Don’t blame the user
- Don’t use technical language (like “server”, “API”, “code”, “backend”)
- Be as clear as possible
- Avoid using humor
- Tell them what happened and how to resolve it
It’s always a good thing to show the message you’re writing to a colleague. Chances are that if they get tripped up on the words, your users will too.
Controlled vocabulary
Finally, at the end of our guidelines, we included a controlled vocabulary. Similar to a glossary, a controlled vocabulary offers a source of truth for words and phrases we use and don’t use.
This resource is valuable for internal teams as it ensures that we remain consistent in how we refer to the interface.
A controlled vocabulary is an evergreen resource that should continuously be tweaked, updated, and questioned.
Feedback is important
Just as feedback from colleagues helps us develop professionally, feedback in a product helps users accomplish tasks efficiently.
Untangling an existing feedback system can be daunting. But if you start with an inventory of your current system, define a hierarchy of feedback types, and create guidelines based on your findings, you will be able to prioritize improvements and reshape your system in sections.
What can this process teach us? That by considering feedback states early in UX explorations, we can save time in the long run and create resilient experiences for our users.
Big thanks to Amelie Sirois, Devin Asaro, Kate Icely, and Ryan Bigge for their writing tips and feedback, and to Marina Verdu for the illustration.
What’s been your experience with creating in-product errors messages and feedback systems? Have you ever gotten tripped up by an error message? Let us know in the comments.
