Crafting user-friendly error messages

In May 2023, the financial services company I worked for adopted a new financial planning vendor software. To help branch teams migrate their data from the old system to the new one, my product team was tasked with creating a migration tool. This effort involved creating new error messages to inform and guide users in case something goes wrong with our migration tool.

Note: Some details and images are not included or have been redacted for privacy reasons


December 2022 - April 2023


UX content strategist (me), UX designer, product owner, business analyst, developers


Mural, Figma, Zeplin

The problem

We identified errors coming from the API. I was tasked with writing messages for our error states.

How might we communicate system errors to users and ensure they are aware of what to do next?

Original copy one of our developers wrote


Writing error messages that include what happened, why it happened, and what to do next will make the data migration less confusing for branch teams if something goes wrong with our system.

We’ll know this is true when we see branch teams taking the appropriate next steps.

What I did

Copy explorations I drafted; UX designer used as a reference for initial wires

One of the prototypes we created


We worked with a UX researcher to test the prototypes with our users.  I updated the copy based on user feedback on the language and the flow (when the messages appeared).

We did find a few more errors on the day of the soft launch. With a better understanding of the user flow and an outline for our error messages, we were able to determine where the error messages should appear and what they should say. We used Pendo, an in-app guide tool we installed on our product, to quickly get those messages out and track analytics. I left the company around this time, so I don't have data that shows how those messages performed.