What a Sensible Error Message Tells the User
A working note on error message design — what matters, what does not, and where these projects usually go sideways.
There is a short answer on error message design and a useful one. The short answer fits in a Slack message. The useful one depends on three things nobody writes down, so we will write them down.
The problem underneath
Teams don't get error message design wrong because they lack skill. They get it wrong because the decision gets made in a hurry, by whoever is closest to the ticket.
Nobody documents it. Six weeks later three people have three different mental models.
That gap costs more than the original choice ever did.
Two real shapes this takes
One common pattern we see: the product works and the process around it does not. Nothing in the code needs changing, but three people are doing manual repair work every day.
The other pattern is the reverse. Process is fine, the system cannot hold the shape the business now needs.
The fixes have almost nothing in common, so guessing is expensive.
Mistakes companies make
- Choosing tools before the workflow is written down.
- Scoping version one to cover every edge case.
- Leaving the work unowned, then blaming the tool.
- Skipping measurement, so nobody can prove it helped.
- Treating launch day as the end of the cost.
The first and the last are the expensive ones.
The engineering view
From inside the codebase, error message design reduces to three questions. What happens when a step fails halfway. Who finds out. How you reverse it.
Design for partial failure before you need it. Step three fails after one and two already succeeded, and that is the case people skip.
Give retries a ceiling and some jitter. A retry storm is an outage you built yourself.
The sequence we use
- Map the workflow on one page, including the manual steps people are embarrassed about.
- Mark where money, time, or trust is being lost.
- Choose one of those, not three.
- Define what "better" means numerically before building.
- Ship a narrow version behind a flag.
- Compare a two-week window either side, then decide.
What good practice looks like here
- One owner, named, with time actually cleared.
- Limits enforced in code so a bad day cannot become a bad invoice.
- A short written record of why the choice was made.
- Alerts that a human reads, not a dashboard nobody opens.
- A scheduled review, because every decision here has a shelf life.
The trade-offs nobody puts in the proposal
Every option here buys you something and charges you elsewhere. Faster now often means a rewrite later, and that can still be the right call.
What matters is naming the bill in advance so it is a decision rather than a surprise.
Where the common advice is wrong
“Do it the way the big companies do.” Their constraint is coordination across many teams. Yours is probably two engineers and a deadline.
“Automate everything.” Automate the repeated, boring, high-volume part. Leave judgement to people.
“Wait until we have more data.” Ship something small and the data arrives.
Frequently asked questions
Is it cheaper to buy a tool instead?
Often yes for the first version. Build when the workflow is a genuine differentiator or no tool fits the data you already hold.
How long does error message design take to get right?
A narrow first version is usually four to six weeks. Anything quoted at three months with nothing shippable in between is a risk, not a plan.
What should we do first?
Write one sentence describing the outcome you want from error message design, then map the workflow it touches. Both take an afternoon and remove most of the guessing.
When is the right time to revisit the decision?
When a second customer asks for something the first one never needed, or when volume changes by an order of magnitude.
Do we need to hire someone for this?
Not at the start. One named owner with a few protected hours a week, plus a small build team, is enough to prove value.
Wrapping up
error message design does not need a perfect answer. It needs a written one, an owner, and a review date.
Pick the version you can run with the team you have today, then revisit it when the constraints change.
Related reading and next steps
- SaaS and web apps — how we run this kind of work.
- custom AI solutions — where this often connects.
- More writing from the team.
Want a second opinion on error message design for your setup? Book a 30-minute call. If it is not worth building, we will say so.
FAQ
Frequently asked questions
Is it cheaper to buy a tool instead?+
Often yes for the first version. Build when the workflow is a genuine differentiator or no tool fits the data you already hold.
How long does error message design take to get right?+
A narrow first version is usually four to six weeks. Anything quoted at three months with nothing shippable in between is a risk, not a plan.
What should we do first?+
Write one sentence describing the outcome you want from error message design, then map the workflow it touches. Both take an afternoon and remove most of the guessing.
When is the right time to revisit the decision?+
When a second customer asks for something the first one never needed, or when volume changes by an order of magnitude.
Do we need to hire someone for this?+
Not at the start. One named owner with a few protected hours a week, plus a small build team, is enough to prove value.
Building something similar?
Let's talk in 30 minutes.