Same-class errors need consistent wording

What it is

Versioned error taxonomy and message governance maps internal reason codes to stable user-facing error classes, then defines each class's name, data state, recovery policy, severity, and channel message keys. The same user meaning keeps one concept; different consequences are not merged merely to reduce templates. Version governance updates UI, email, status, help, and support together when rules change and handles unknown or stale mappings.

Why it happens

Implementation reason codes are often finer or coarser than user concepts. Several endpoint timeouts may all mean temporary unavailability, while one code can imply different states in payment and draft contexts. Generating copy directly from codes creates drift or incorrect recovery. A taxonomy first classifies user-visible outcome, recoverability, responsible actor, and risk, then maps internal codes into it. Message assets and recovery actions share a version so copy cannot say “Retry” after the action becomes unavailable. Unknown mappings degrade safely rather than reusing stale authorization or guessing a class.

Studying it

Collect cross-channel error events, messages, user actions, and support outcomes. Cluster by user state and recovery path, then have engineering, content, support, and risk owners review splits and merges. Use confusion matrices to detect inconsistent names for one class and merged classes with different consequences; track self-recovery, repeated failure, and escalation by channel and version. Replay historical events after taxonomy changes to ensure new mappings do not alter recorded meaning or erase unknown states.

Where it stops holding

Consistency is not literal identity. A toast, email, and support script can adapt to space and conversation while preserving error class, state, and recovery promise. Each language may express the class naturally. The taxonomy is not a public security-rule list and must not expose protected internal causes; public messages consume only approved fields. One-off faults still need an unknown path but do not each require a new user-facing class.

Applying it

• Record class ID, definition, outcome, data or transaction state, recoverability, responsible actor, severity, safe disclosure, recovery action, owner, version, and message keys.
• Maintain conditional many-to-one mappings from reason codes to user classes and publish one version bundle across channels. CI checks missing, conflicting, and stale mappings plus recovery-action availability.
• On taxonomy change, produce an impact manifest and update UI, notices, status pages, help, support macros, and analytics together. Preserve old-version interpretation for historical events rather than silently rewriting audit records.
• Monitor unknown rate, cross-channel version skew, and recovery differences within a class. Unknown uses a safe fallback and public reference ID, then enters the classification review queue.

Related

• Same group: T2.04.1 Say what happened, why, and what to do · T2.04.2 Do not blame the user in error messages · T2.04.3 Do not expose internal technical detail · T2.04.4 Do not joke away real losses
• Adjacent: T1.04.2 The glossary must cover interface, docs, and support · T3.04.2 Multi-channel content needs a single source of truth
• Search terms: error taxonomy · reason-code mapping · message version governance