# Which Problems Are Solved
The API error reference page (`/docs/apis/errors`) shows "Couldn't load
the error reference. Try reloading the page." instead of the table. This
started after #12502 switched the page from a static import of
`data.json` to fetching it from a route handler at runtime.
# How the Problems Are Solved
`apps/docs` is served under `basePath: '/docs'` (`next.config.mjs`). The
fetch call in `ErrorReference` used `/api/error-reference`, but a plain
`fetch()` does not get the basePath prefix added the way `<Link>` and
`router.push()` do, so the request always 404'd. Fetches
`/docs/api/error-reference` instead, the actual prefixed route.
# Additional Changes
None.
# Additional Context
- Follow-up for #12502
- Confirmed locally: `curl localhost:3000/api/error-reference` returns
404, `curl localhost:3000/docs/api/error-reference` returns 200 with the
full catalog
Co-authored-by: Rajat Singh <[email protected]>
## Summary
- Add a searchable catalog of every error ID ZITADEL's gRPC/Connect APIs
can return (`content/apis/errors.mdx`), wired into the sidebar next to
"gRPC Status Codes" (with a cross-link added there too). There was
previously no such reference — error IDs are assigned ad hoc at ~3,800
call sites across the backend.
- `scripts/generate-error-reference.ts` scans `internal/**/*.go` and
`backend/**/*.go` for `zerrors.Throw*()` call sites, resolves i18n
messages, and clusters ~3,200 distinct IDs into ~1,160 distinct causes
by (subsystem, gRPC code, message) — so identical causes are merged into
one entry instead of repeated ~3,200 times.
- Detects real ID collisions (same ID thrown for genuinely different
reasons at different call sites) and surfaces them as warnings, rather
than silently merging them.
- Generates a worked example API response for every cause.
- 116 of the highest-impact causes (covering the majority of call sites)
carry an explanation written against the actual source rather than the
raw message text; the rest carry a mechanically derived explanation —
both are visibly labeled by source so the depth of research is
transparent.
- New `ErrorReference` component renders the catalog as a searchable,
collapsible subsystem → gRPC code → cause tree.
The generator is a standalone script (`pnpm generate:error-reference` in
`apps/docs`), not wired into the docs build's `generate` chain, since
scanning the whole Go backend on every docs build would be wasteful. The
generated `data.json` and the curated overrides are committed, the same
way `content/apis/benchmarks/**/output.json` is already committed
despite being externally generated.
## Test plan
- [x] `pnpm nx run @zitadel/docs:check-types` passes
- [x] `pnpm nx run @zitadel/docs:lint` passes
- [x] `pnpm nx run @zitadel/docs:check-links` passes
- [x] Verified locally in `pnpm nx run @zitadel/docs:dev`: page renders,
tree expands/collapses, search filters by ID/message, collision warnings
render correctly (e.g. `AUTHZ-Kl3p0`)
---------
Co-authored-by: Rajat Singh <[email protected]>
Co-authored-by: Claude Sonnet 5 <[email protected]>
Co-authored-by: Marco A. <[email protected]>
