Every Screen Needs an Error State

Error states are the most-skipped requirement class in product specs, and it is not because they are hard. It is because you write a requirement while imagining it working. The failure path never enters the sentence, so it never enters the document, and it gets decided months later by an engineer under deadline who reaches for the generic toast.

This post is about what to write instead. It assumes you have already found the failure conditions — the five lenses do that job — and picks up at the harder question: what does the spec actually say once you have one?

Why they get skipped

Three reasons, all structural rather than lazy.

The happy path is the idea. You are specifying a capability, and the capability is the thing succeeding. Failure feels like a detail of implementation rather than a description of the product.

Errors have no obvious owner. Design owns the screen, engineering owns the exception, and the PM owns the requirement — so the error state falls in the gap between all three and is claimed by none of them.

They are invisible in review. Nobody reads a PRD and notices an error state that is not there. Missing sections are visible; missing conditions inside a section are not, which is why this particular gap survives review so reliably.

The seven failure modes

You do not need a case per fault. You need one specified behaviour per class, and named exceptions where a particular error deserves its own treatment.

1 · Validation. The user gave you something you will not accept. Wrong format, missing field, value out of range. The most common class and the most commonly under-specified — inline or on submit, per-field or summarised, and does the form retain what they typed?

2 · Permission. They are allowed to be here, not allowed to do this. Distinct from authentication. The decision to specify is hidden or disabled, and both are defensible — hiding avoids frustration, disabling teaches the model. Pick one and say why.

3 · Not found. The record is gone, the link is dead, the URL was guessed. Worth distinguishing "never existed" from "you can no longer see it", because the second is a permission leak if you phrase it carelessly.

4 · Conflict. Someone else changed it while the user was working. The one users find most distressing, because their work is at stake. Last-write-wins is a decision — make it deliberately.

5 · Limit. Seat cap, quota, rate limit, storage. Almost always under-specified relative to how often it fires. Does the user get told before they hit it, or only after?

6 · Dependency failure. Something you call did not answer. Payment provider, email service, integration, model API. The class most likely to be entirely absent from a spec, and the one most likely to embarrass you at launch.

7 · Unknown. Something broke and you cannot classify it. You need exactly one of these, written well, because it is the catch-all everything unspecified falls into. If it is the only one you write, every failure in your product looks identical to the user.

Five things to write for each

An error requirement is not a sentence. It has parts, and skipping any one of them is where the implementation drifts.

Trigger. The condition, precisely. Not "if the upload fails" but "if the upload exceeds 10MB, or the file type is outside the allowed list, or the storage call returns non-2xx".

What the user sees. Where it appears — inline, banner, full page, modal — and what it means. You are specifying the meaning, not the wording.

What they can do next. Retry, edit, go back, contact support, wait. An error with no action is a dead end, and dead ends generate tickets.

What happens to their work. The single most important line and the most frequently missing. Is the form retained? The draft saved? The upload queued? A user who loses fifteen minutes of input to a network blip will not care how good the message was.

Who else finds out. Logged, alerted, surfaced to an admin, counted in a metric. Errors nobody can see are errors nobody fixes.

The message test

Three questions, applied to any error message. A good one answers all three.

What happened? · Why? · What now?

"Something went wrong." — none.

"Error 429." — one, in a language the user does not speak.

"We could not reach the payment provider. Your card was not charged. Try again in a minute." — all three, and the middle sentence is doing the most work. It answers the question the user was already forming, which is the one that would otherwise become a support conversation.

Specify the meaning and the required elements in the PRD, then let whoever owns copy write the words. A spec that says "explain the failure, confirm no charge was made, offer retry" gives a writer everything. A spec that says "show an error" guarantees the generic default.

Errors are a surface, not an exception

The framing that changes how much attention this gets: your error states are not the edge of your product. For any user who hits one, they are the product for that minute — and it is the minute they are most likely to leave, most likely to write to you, and most likely to remember.

That is worth roughly the same specification effort as the happy path it interrupts. Not more. But nowhere near as much less as most PRDs give it.

A practical test before your spec goes to review: take any requirement and ask what a user sees when it does not work. If the honest answer is "a red box, probably", the requirement is not finished — and it will ship that way, because nothing downstream of the PRD is going to catch it.

FAQ

What is an error state in a PRD? The specified behaviour when a requirement cannot complete — what the user sees, what they can do, and what happens to their work.

Which errors need specifying? Seven classes: validation, permission, not-found, conflict, limit, dependency failure, unknown. One behaviour per class, plus named exceptions.

What makes a good message? It answers what happened, why, and what now — in the user's terms.

Should the PRD write the copy? Specify the meaning and required elements; leave the wording to whoever owns copy. "Show an error" is not a requirement.