docs: add error reference and catalog appendix to user-facing-errors

[jhickmanit]

What

Adds an Error reference section and a Kratos error catalog code appendix to the Kratos user-facing errors page (docs/kratos/self-service/flows/user-facing-errors.md).

The Error reference is a lookup table for the errors operators and integrators hit most often, grouped by where they originate:

• Session and whoami (403 causes: cookie domain, AAL step-up, CSRF, privileged session)
• Self-service flow errors (flow expiry, duplicate identifier, browser_location_change_required)
• OAuth2 and OIDC (Ory Hydra: invalid_grant, invalid_client, token-hook server_error)
• Self-service callouts and hooks (can_interrupt behavior, webhook 502s)
• Network and project plumbing (custom domain 404, ory_pat_ vs ory_wak_, 431)
• Rate limiting (429)

The appendix maps every 4xxxxxx catalog code to its identifier and literal message.

Verification

• Content verified against ory-corp/cloud (HTTP statuses, config keys, error codes, identifiers, literal messages).
• Error codes are identical across OSS / OEL / Network, so no deployment-mode branching/tabs are needed.

Voice

Product naming intentionally matches the existing page's voice (Ory Kratos / Ory Hydra) so the page reads consistently. A future pass can re-voice the whole page (intro + this section) to the directory's dominant Ory Identities voice together.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added a new error reference section to help interpret self-service error responses.
  • Included structured lookup tables for common issues across login, registration, settings, recovery, verification, OAuth2/OIDC, webhook, infrastructure, and rate-limiting scenarios.
  • Added an error catalog appendix that maps validation codes to readable messages, with notes for dynamic error text.

[Copilot]

Pull request overview

Adds a structured, operator-focused “Error reference” lookup table and an “Error catalog code appendix” to the existing Kratos user-facing errors documentation page, to make common production error diagnosis faster without needing to cross-reference source code.

Changes:

• Adds an “Error reference” section grouping common errors by origin (session/whoami, flows, OAuth2/OIDC, hooks, network plumbing, rate limiting).
• Adds an “Error catalog code appendix” mapping 4xxxxxx validation catalog codes to identifiers and literal messages.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds an error-reference section to the Kratos self-service user-facing errors guide, with lookup tables for common runtime failures and an appendix that maps validation catalog codes to identifiers and message templates.

Changes

Kratos self-service error reference

Layer / File(s)	Summary
Error reference lookups docs/kratos/self-service/flows/user-facing-errors.md	Adds the error-reference introduction and lookup tables for session, self-service flow, OAuth2/OIDC, hook, network, and rate-limiting failures.
Error catalog appendix docs/kratos/self-service/flows/user-facing-errors.md	Adds the catalog-code appendix and the login, registration, settings, recovery, and verification code tables.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 I hopped through errors, one by one,
With lookup tables neatly done.
Codes and clues now softly gleam,
In Kratos docs, a bunny’s dream!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the docs change by naming the new error reference and catalog appendix.
Description check	✅ Passed	The description explains the change, verification, and context well enough for a documentation-only PR, despite not mirroring every template section.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs-kratos-error-reference

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/kratos/self-service/flows/user-facing-errors.md`:
- Line 118: The appendix intro in user-facing-errors.md incorrectly claims the
listed flow-expiry strings are literal catalog text, but the rows normalize
runtime placeholders like X minutes ago. Update the introductory sentence near
the catalog-code appendix to clearly mark the table as a template/reference
rather than verbatim source text, and keep the wording consistent with the
flow-expiry entries so the interpretation matches the content.
- Line 85: The refresh-token guidance in the user-facing errors table
incorrectly tells users to check an `exp` claim, but refresh tokens in Hydra are
opaque and have no embedded claims. Update the row text in the document so it
only advises on rotation, timeout, and revocation causes, and reference the
refresh-token entry in the user-facing errors table to keep the wording aligned
with Hydra’s token model.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 4f7f8443-578f-4477-9c42-1b4725eca81e

📥 Commits

Reviewing files that changed from the base of the PR and between 92dcfb2 and aa09cb3.

📒 Files selected for processing (1)

• docs/kratos/self-service/flows/user-facing-errors.md

[vinckr]

we already have https://www.ory.com/docs/kratos/concepts/ui-messages - which seems to be orphaned?

please make sure we aren't duplicating stuff here, also an index of all UI errors is autogenerated here: https://github.com/ory/docs/blob/master/docs/kratos/concepts/messages.json