Errors
Allows users to fix problems themselves through thoughtful messaging.
Overview
An error occurs when something else happens from the initially expected result. It comes in various formats and types, from forgetting to fill in a field to a 404 page by way of some action being impossible to perform.
Errors can happen to any role using the Mirakl platform in many different situations. But what they have in common is that they confuse, annoy, stress, or cause extra work for Mirakl users.
That's why messages should follow UX writing principles (clear and useful especially) and always have the user's feelings in mind.
For sure, an error temporarily breaks the experience, but it does not have to end it.
Guidelines
Focus on the solution, not the problem
Even though it is super important to explain what happened to our users, focus on what they can do to fix the issue, even though it may sound vague to you ("Try again later").
The main takeaway is don't focus on what the user did not do or did wrong. Help them understand what they can do.
Impossible to load your order list. Try again later.
Your order list would not load.
Provide at least one email address.
Provide at least one email address.
Use generic language but technical terms
Our users know their business and the vocabulary that comes with it. But this does not mean we write complex sentences and use unneeded jargon. Write error messages in plain language and focus on clarity.
The code challenge you entered is invalid.
Invalid "code_challenge" parameter
Don't blame the user
Surely you need to explain what kind of problem happened, but this does not mean you have to blame them, even if they are responsible. Focus on the action they need to take to solve it. Always put the error into perspective to de-dramatize the situation when possible.
Remember to provide your billing address.
You forgot to add your billing address.
Be as precise as possible (and it's ok if sometimes you can't)
To help users solve their problems, they must first understand what happened. Be as precise as possible when explaining: is it a limited-time problem? Did they forget to add information in a form? Is it the service's fault?
Take the space you need to explain what is going on. If you do not have the space to do so, ask your designer to switch components.
Sometimes, you don't know what's happening and can't be as precise as you wish. Be generic, then, but without being unclear.
You cannot delete a section that contains at least one custom field.
Something went wrong while updating your order. Try again in a few minutes.
Users don't care about the technical stuff (most of the time)
Even if our product tackles complex processes, that doesn't mean we have to sound complex or showcase our technical knowledge. That's the same for error messages. Focus on what users need to do with terms they understand.
You have made too many requests recently. Wait for a while and try again.
Time out, too many requests recently.
In certain circumstances, technical information like error codes can be useful to some users (think developers). You may add them at the end of your message or in the following line.
No jokes, no puns; watch your tone.
Users facing errors can feel stressed or panicked depending on the size of the problem. This is not the time to make puns or jokes that could increase this feeling and delay them in solving the error.
Our platform is temporarily down
Oops, impossible to log in.
Content
As writers and designers, we love creating efficient and delightful user experiences. Even if something goes wrong, let's ensure the experience we offer is as efficient as possible and gets users back on the right track.
There are 3 main parts within an error message: the explanation of what went wrong, the why, and the focus on how to fix the issue.
1. What went wrong
Let's start by explaining the issue, whether small or big. Be as clear as possible with the user in mind and try to use generic language.
You are not authorized to access this page.
Impossible to upload your file
Do not apologize for minor issues; only say sorry for major issues.
Depending on the components, this information will be placed as a title (empty state, alert) or within the message (snackbar, form field).
2. Why
Users are more likely to tolerate the error if they understand why things went wrong. If there's enough space in your component, include it.
You cannot reply to this conversation because seller-operator messaging is disabled.
Unable to upload your file because it exceeds the 1 MB size limit.
You cannot reply to this conversation.
3. How to fix the issue
Two options here:
Users cannot do anything about the issue: explain what the product is doing.
Users can do something: explain what they can do instead, or even better, provide a way out within the error message, like a button.
Impossible to load your order list. Try again later.
The requested resource is currently unavailable. The issue is being fixed so the resource can become available again soon.
Examples in components
Alerts highlight important information that needs to be communicated quickly to the user. If the alert describes an error, the content must explain how this error can be fixed.
Empty states should be used when the expected content cannot be displayed. When the user faces network or generic technical issues preventing us from showing them the data they are looking for, text should be clear on what is happening and if the user can do anything about it.
When submitting information within a form, users can encounter errors. Make sure users know how they can fix these errors themselves.
Snackbars only appear for 5 seconds and should be used for minor errors only.
Checklist
Is it a blocker?
If yes | Mind your tone, and explain what is happening. |
If no | Be clear and concise, and focus on the solution. |
Is the user persona technical?
If yes | Then you may add an error code at the end of your message and use technical jargon. |
If no | Focus on what users need to do with terms they understand. |
Do you know what caused the error AND is it important for the user to know?
If yes | Be precise about what went wrong but quickly switch to how users can fix the issue. |
If no | Focus on the solution. |
Last updated
