Error messages that tell users and agents what to do next

What it is

An error message is the interface's answer to two questions that Google's course on error messages (cited) puts at its centre: what went wrong, and how does the user fix it. The course's rules are to explain the problem, identify the cause and the invalid input, specify requirements and constraints, and explain the solution. Microsoft's guidance (cited) asks that a message give a problem, a cause and a solution and be written from the user's point of view. For a message read by a program or an agent, the same content must be available as fields, not only as prose.

Why it matters

A vague message ("Invalid request") produces a support ticket, a guess, or, from an automated client, a loop of identical retries. The message is often the only documentation the reader has at that moment. The Rust compiler's approach (cited) shows how far this can be taken: diagnostics carry structured suggestions labelled with an applicability level (MachineApplicable, HasPlaceholders, MaybeIncorrect, Unspecified), so tools apply automatically only the ones marked as mechanically applicable.

How to apply

• Name the thing: the field, the file and line, the actual value received, and what was expected instead ("start_date: expected an ISO 8601 date such as 2026-09-15, got 15.09.2026").
• State the constraint, not just the failure: the limit, the allowed set, the required format.
• Say what to do next, and whether doing the same thing again can succeed: distinguish "fix the input", "wait and retry" and "contact the operator" explicitly.
• Give each distinct cause its own message and a stable, searchable identifier; keep the identifier constant across releases even when the wording improves.
• For agents and clients, provide the parts as fields: code, field, expected, received, retryable, documentation link; the Problem Details format for HTTP APIs (see the related article) is one carrier.
• Keep suggested fixes separate from the statement of the error, and label how confident they are, as the Rust guide does; a wrong suggestion applied automatically is worse than none.
• Never expose internals to end users (stack traces, hostnames, SQL, secrets); log those with a correlation ID the message shows.
• Write in plain words, without blame, double negatives or humour; test each message by asking "what would I do now?".

Pitfalls

Catch-all messages that hide the cause. Messages that change wording every release and break parsers. Suggestions that are wrong more often than right. Validation errors reported one at a time when the client sent ten fields. Leaking whether an account exists through different messages for "wrong password" and "unknown user".