5 Tips for Writing Great Error Messages

A good error message is part of creating a good user experience. While encountering them as an end user may cause frustration, a comprehensive error message can provide the necessary insights to debug and troubleshoot effectively.

When it came to building our new Detailed Error Messages feature — now available to all Merge customers, we knew it was important to consider not only what types of errors but how to communicate those errors. These are shown to our customers’ end users when they interface Merge Link.

Merge Link is our seamless UI component that guides our customer’s end user through setting up an integration with just a few clicks. Merge Link can be easily embedded into our customer’s app, showcasing the different integrations that are available via Merge. 

Because Merge Link is the main interface that our customers’ end users will use, and is part of our customers’ product experience, we knew it was crucial to invest time and effort into building out custom error messages for challenging integrations. These integrations are more complex to authorize than the simple, “Sign in with your credentials and share the API key.”

Ankit Deshmukh and Lee Wang on our engineering team and Yash Gogri on our post-sales team shared 5 key takeaways when it comes to writing error messages:

1. Find the most common errors

In order to make sure our detailed error messages would have the highest impact, our team looked at product data involving thousands of customers using the 100+ integrations we support. 

We looked at the most frequently used integrations, the percentage of successful linked accounts at the integration level, as well as customer feedback to prioritize which integrations to add detailed error messages and the types of error messages. 

Because we chose the right starting points, we’ve already seen over a 30% increase in our linked account success rate for HRIS integrations during the beta phase.

Related: 5 API error handling best practices

2. Keep the error messages simple

We wish we didn’t have to write this, but legendary error messages like, “Task failed successfully,” made us think twice. Detailed error messages need to be simple and easy for readers to understand.

Merge Link’s interface makes it easy for any business user to access the technical power of APIs. That means error messages need to be written in a way that’s accessible across all levels of technical understanding.The end user might be an HR manager who might not know what an API is. 

When we wrote our error messages, we kept the messages clear and direct, focusing on the problem and steps required to solve it, and avoided any jargon or philosophical paradoxes.

3. Display a helpful call to action

Sometimes, an error can be so complex that a concise message wouldn’t help. Having a clear call to action that directs to a longer help center article, with videos and/or screenshots can be the next step an end user needs when the error message may not be sufficient enough.

4. Consider the backend logic and rules so the proper error message appears

Our engineering team needed to make sure the correct error messages popped up at the right time. 

After careful consideration and planning, they had to code the logic to ensure the correct error message displayed based on specific triggers. 

For example, showing the main error message that caused downstream errors enables the end user to find a resolution. If they don’t see the right error message, it would result in unresolved issues, an ineffective error reporting system, and an endless bout of headaches.

5. Test, test, and test some more!

The most important thing that the team did when building this feature was testing each integration’s linking flow, putting themselves in the perspective of a Merge Link end user. 

This made sure our team captured edge cases and addressed any additional areas of confusion in the linking flow. Going through the actual user experience is crucial, there’s no shortcut around this! 

See Detailed Error Messages in Action

Detailed error messages will enable our customers’ support teams to save time, and guide end users to independently troubleshoot integration issues. 

Not only can this save hours of each of our customers’ support team’s time, it also delivers a better in-product experience. Best of all, Merge Link can take care of all of this, so our customers don’t need to spend time thinking through and building their own error logic and messages.

Want to see this in action? The Detailed Error Messages feature is available to everyone, including those on our Launch plan where customers can start on for free! Sign up now.

If you’re looking to learn more about Merge and see it in action, you can get a demo.