Do not use an error code as the only information

What it is

An error code belongs in logs, support tickets, and version tracking, but it cannot substitute for user-readable explanation. The interface should first state what happened and what the user can do, then put the code, request ID, timestamp, and technical detail into an expandable or copyable area. This does not conflict with the other three cards in the group: they require content, location, and a recovery path all to be present; this one addresses where the code should sit once those three are in place — beside them, not in their place.

Why it happens

Most users have no code lookup table and no way to reverse-engineer a hash-like ID into whether the failure was a permissions, network, or input problem — an error code is an opaque symbol to a user, meaningful only against internal documentation or a ticketing system. Showing only a code shifts the cost of diagnosis from the system and support team, who are equipped to bear it, onto a user who has no tooling to do so at all. Even for insiders, cross-system version upgrades and localized translation can make the same code mean different things across time and teams, a kind of drift that makes the code itself an unstable reference in the long run — the only thing that stays genuinely stable is the log entry bound to it. The real value of an error code lives at the other end of the diagnostic chain: it is the key for precisely searching logs, stitching together calls across systems, and aligning the same incident across teams — a key the user cannot turn themselves. What the user layer needs is task facts and a next action; the code is incidental evidence meant for someone else to use.

Where it stops holding

Technical detail is not always safe to expose: a stack trace can contain internal paths, hostnames, or unmasked personal data, and showing it directly to an end user is a disclosure risk, not help — a security system should have a dedicated masking policy that decides what, if anything, is allowed to surface in the UI. A developer-facing advanced view — an admin console or debug mode — can show a fuller stack and raw response, because that audience can interpret it; hiding the code there is over-protection that slows down their troubleshooting. This principle targets ordinary task interfaces, not developer tooling. Error code naming and meaning must also track releases: if the same code silently changes meaning between two releases without a documentation update, support staff following the old documentation will draw the wrong conclusion about a new problem — a risk more hidden and more dangerous than a user simply not understanding a code.

Applying it

• Maintain a mapping table from error code to user copy, recovery action, and support path, treat it as part of the release checklist, and regression-test it with every version to catch code-meaning drift before the copy falls out of sync.
• Keep the primary message area in task language only; put the error code, request ID, and timestamp in an expandable "details" section with one-click copy.
• Support forms should auto-attach masked diagnostic data rather than requiring users to hand-copy codes and timestamps, since manual copying is itself an error-prone step.
• How to check: replay real historical errors and have an ordinary user, an internal admin, and a frontline support agent respond to the same error screen, checking whether all three get an answer at the level they actually need — the ordinary user understands the task consequence, the support agent can locate the log.

Related

• Same group: B3.09.1 Error messages should explain the problem in plain language · B3.09.2 Pinpoint the location of the problem · B3.09.3 Provide an actionable path forward
• Nearby: R2 Engineering Delivery · Y3 Error Prevention and Recovery
• Search terms: error code · request id · support diagnostics · log correlation