Error Message

Before the text inside a product was treated as design work, the words that appeared when something broke were usually whatever leaked out of the code. "Error 500." "Invalid input." "An error occurred while processing your request." These read like notes a developer left for themselves: they describe the failure in the system's vocabulary and say nothing about what the person reading is supposed to do next.

From the reader's side, the path just ends. Continuing the task requires knowing the cause, the screen doesn't supply one, and what's left is pressing the same button a few more times or asking a human.

Pagedeck went through this. The most frequent request reaching Sofia was "saving doesn't work," and the screenshot attached always showed the same line: an error occurred while processing your request. Sofia couldn't answer from that line, so she asked Theo, and Theo opened the logs and found that the file had exceeded the size limit. One different sentence on screen would have saved all three people their time.

An error message is what you get when that moment is promoted into something worth writing deliberately. It doesn't try to remove the error. It changes the problem into making sure a user can get out of it alone.

Three things happen in order inside the text: it names what happened, narrows down why in human terms, and hands over something to do next. When the first two are there and the third isn't, the reader goes to support.

1. State. Name the action that failed. Not "an error occurred" but "we couldn't save your document." Knowing which action failed is how someone works out what they just lost.
2. Cause. Write the condition in terms the reader can check, not in system terms. Not "413 Payload Too Large" but "this file is over 25MB." Sometimes the cause genuinely isn't knowable, and then the honest move is to give the range instead of inventing one — a sentence saying this is on our side and retrying in a moment should work.
3. Next action. Offer one thing the reader can do immediately, and offer it as a button rather than a sentence where possible. A message about file size sits next to a "choose another file" button; a message about a dropped connection sits next to "try again." The button label, which tells people what pressing it will do, carries half the message here.

Two smaller rules attach to this. One is the direction of blame. "You entered an invalid value" points at the reader, while "this field accepts numbers only" states a condition. Same fact, and the second is closer to an action. The other is what to do with technical detail. Don't delete the error code — move it out of the sentence and leave it as a small reference number. It's useless to most readers and it is the only thread Sofia can hand to Theo when a ticket arrives.

The same words get read or get missed depending on where they appear. There are roughly four places.

1. Next to the field. Anything caused by one specific input — a wrongly formatted value, a missing required entry — belongs directly under that field. Collecting these at the top of the page means hunting through a twenty-field form for the one that's wrong. A placeholder, the faint example inside an input, can't do this job: it disappears the moment typing starts, which is exactly when it would be needed.
2. The whole screen. When a list fails to load or the account lacks permission, the screen doesn't hold together at all, and the work is designing an entire error state rather than one line. It looks much like the empty state copy shown when there's nothing to display, so the sentence has to make clear whether there is no data or the data didn't arrive.
3. Banners and toasts. Use these for problems that don't block the current task, such as a save that succeeded while syncing lags. Never put anything irreversible in a toast that vanishes after a few seconds — someone who stepped away never sees that line.
4. Outside the product. If a failed payment will suspend an account, saying so only inside the app is too late. Mail and push notifications reach someone who isn't looking at the product, so what happened and where it happened both have to fit in the first line.

One question decides the placement: does this problem block what the person was trying to do? If it does, attach it where that action happens, close enough that the eye lands on it without searching. If it doesn't, keep it out of the flow, because an interruption that costs attention for something the reader can ignore trains them to dismiss the next one unread.

"This error message has the cause but no next action."

Nobody knows what to do after reading it, so add the missing line.

"Let's not surface the raw 500 — just leave a reference number."

Keep technical detail for the support desk and write the screen in human language.

"This needs to be inline. Nobody reads a toast at the top of the page."

It's too far from the field that caused the problem to be seen.

At Pagedeck, Noa lists the ways a screen can go wrong before drawing the screen. File too large, connection dropped, no permission — the list comes first, each line gets its text, and only then does the layout get built around those lines. Reversed, the words have to be squeezed into a width that already exists, and the first things cut are the cause and the next action.

The most common belief is that an apology makes an error message kind. Saying sorry does show an attitude, so the assumption is reasonable. But what the reader wants is a next step, not sympathy. "Sorry, an error occurred" contains two sentences and neither of them expands what the reader can do. Once this belief settles in, editing error text narrows into choosing apology wording, while messages missing a cause and an action stay exactly as they were.

The other is assuming text can be filled in after the screen is built. Sentences feel endlessly editable, so it looks safe. In practice, once the space is fixed the words get fitted to it. A slot with room for one line forces a choice between the condition and the next action, and the next action usually loses. Leaving placeholder sentences in a mockup does the same damage: the screen goes to engineering without anyone having checked whether it reads.