Pattern — Error page

Status: v0.1.0 — Draft. Promoted from the KDS × gov.br Design System gap analysis (tools/design-gen/docs/govbr-ds-gap-analysis.md, GVB-17). Source: gov.br Padrão Digital erro template + busca-erro (embedded Intelligent Search for recovery).

R1 — When to use (vs inline error / confirmation)

• Error page (this): a whole-page failure the user landed on — a bad URL (404), a server fault (500), no permission (403), an expired session, or an unavailable service. The page replaces the content.
• Inline error (specs/errors/user-facing-messages.kmd): a scoped failure within an otherwise-working surface (a field, a form, a widget) — do not escalate to a full page.
• Confirmation page (specs/patterns/confirmation-page.kmd): the success/next-step counterpart — same template family, opposite outcome.

R2 — Message: what + why + how to fix

• State, in plain language, what happened ("This page can't be found"), optionally why when it helps ("The link may be broken or the page may have moved"), and how to recover (the actions in R3/R4).
• Humanized per specs/errors/user-facing-messages.kmd: no codes or stack terms in the primary message, no blame, no dead-end "Error 500". A technical reference id may appear secondary (small, copyable) for support — never as the headline.
• Map the copy to the error class per specs/errors/taxonomy.kmd (404 / 403 / 500 / 503 / expired) — each class has a distinct message and recovery set.

R3 — Embedded search (the core rule)

• The error page embeds a search box so the user can immediately look for what they wanted instead of hitting a dead end (the gov.br busca-erro model). On a 404 especially, search is the primary recovery.
• The search is a real, focusable input with a clear label and submits to the site/app search. Where possible, pre-seed it from the failed path or query.

R4 — Recovery links & primary action

• Alongside search, offer a small set of recovery links: Home, the parent section, "go back", and — for auth/permission/expired — a sign-in / renew-session primary action.
• Exactly one primary action appropriate to the class (Home for 404; Sign in for expired; Retry for a transient 503). Secondary links are quieter.
• Never leave the user with only a message and no way forward.

R5 — Illustration / empty-state tone

• Pair the message with an illustration or empty-state graphic (specs/patterns/empty-state.kmd) that sets a calm, non-alarming tone. Decorative art is aria-hidden; it never carries meaning the text lacks.
• Keep the page uncluttered — message, search, actions, illustration. Reuse the standard page chrome (header/footer) so the user is not stranded outside the app shell.

R6 — Behavior & status

• Serve the correct HTTP status for the class (404/403/500/503) — the visual page and the status code must agree (SEO + client handling).
• A transient error (503/timeout) may offer Retry; do not auto-reload in a loop. Log/report per specs/errors/reporting.kmd without exposing internals to the user.

R7 — Accessibility & i18n

• The page has a real <h1> with the error summary; focus lands on the heading or the search on load. The status is conveyed in text, not color alone.
• Search and recovery actions are keyboard-reachable and labeled.
• All copy (per-class messages, search label, recovery links, primary action) is translatable per specs/i18n/contract.kmd; the reference id is not translated.

Não-escopo

• Inline/field-level error handling (specs/errors/user-facing-messages.kmd, specs/patterns/form-validation.kmd).
• The success/next-step surface (specs/patterns/confirmation-page.kmd).
• Error telemetry/reporting internals (specs/errors/reporting.kmd).
• Maintenance/status-page communication (a separate ops surface).