Error Message Registry
Component Detail
Description
Static registry mapping every application error code to a plain-language two-part message object containing a cause description and a corrective action. Loaded at app startup from a bundled JSON asset. Supports Norwegian (primary) and English fallback.
error-message-registry
Summaries
The Error Message Registry transforms cryptic system errors into clear, actionable guidance that users can actually understand and act upon. By presenting every failure in plain Norwegian (with English fallback), the app eliminates user frustration at critical moments — reducing support call volume, increasing task completion rates, and building long-term trust in the product. A user who understands why something went wrong and knows what to do next is far less likely to abandon the app or contact support. This component is shared across all features, meaning the investment delivers consistent, professional error communication everywhere in the product simultaneously, with zero additional cost per feature.
The Error Message Registry is a low-complexity, shared infrastructure component that can be delivered early in the project and reused across all features without rework. Its only external dependency is a bundled JSON asset, so it carries no integration risk and no API availability concerns. It must be completed before any feature that surfaces user-facing errors — making it a natural early-sprint deliverable. QA must verify Norwegian and English locale switching, fallback message behavior for unknown codes, and asset loading on cold start.
Because it is shared and stateless, regression risk is low and maintenance burden is minimal once the initial error code catalogue is established.
The Error Message Registry is a stateless singleton loaded at app startup via `loadFromAsset(path)`, parsing a bundled JSON file into an in-memory map keyed by error code string. The `lookup(errorCode)` method returns a `PlainLanguageError` value object containing a cause string and a corrective action string; `getFallbackMessage()` provides a safe default for unmapped codes. Locale selection is handled by inspecting the current app locale at lookup time, with Norwegian as primary and English as fallback. The `register(errorCode, message)` interface supports test injection without touching the asset.
Because there are no external dependencies, this component is trivially unit-testable and introduces no async complexity. The primary evolution concern is keeping the JSON asset in sync with new error codes introduced by other services.
Responsibilities
- Load error code–to–message mappings from bundled asset on startup
- Return a structured PlainLanguageError for any given error code
- Return a safe fallback message for unknown error codes
- Support locale switching between Norwegian and English
Interfaces
lookup(errorCode): PlainLanguageError
register(errorCode, message)
loadFromAsset(path)
getFallbackMessage(): PlainLanguageError