mirror of
https://github.com/andwati/zitadel.git
synced 2026-10-18 05:52:51 +00:00
e8d95f306b
## 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]>
44 lines
3.1 KiB
Plaintext
44 lines
3.1 KiB
Plaintext
---
|
|
title: API error reference
|
|
description: Every error ID ZITADEL's gRPC/Connect APIs can return, grouped by subsystem and cause, with why each one happens and an example response.
|
|
sidebar_label: Error Reference
|
|
---
|
|
|
|
import ErrorReference from '@/components/ErrorReference';
|
|
|
|
An error from a ZITADEL gRPC/Connect ("resource") API looks like this:
|
|
|
|
```json
|
|
{
|
|
"code": 16,
|
|
"message": "Token is invalid (AUTH-7fs1e)",
|
|
"details": [
|
|
{
|
|
"@type": "type.googleapis.com/zitadel.v1.ErrorDetail",
|
|
"id": "AUTH-7fs1e",
|
|
"message": "Token is invalid"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
`code` is the gRPC status code — see [gRPC Status Codes](/apis/statuscodes) for the full mapping to HTTP statuses. `details[].id` is a free-form identifier assigned by hand at the source call site (a package prefix plus a short random suffix) — it is **not** a stable, structured error code, and the same ID string is occasionally reused for more than one distinct condition (flagged below where it happens). `details[].message` is either translated for end users or, for internal/operator-facing failures, a literal diagnostic string that's never translated.
|
|
|
|
This `zitadel.v1.ErrorDetail`/`id` shape is what every error on this page currently uses. It isn't the only shape, though: the server picks `zitadel.error.v2.ErrorDetail`/`slug` instead whenever an error's ID is dot-separated rather than dash-separated (see [Error details and slugs](/apis/statuscodes#error-details-and-slugs)) — no call site does that yet, but new ones may. Check `details[]`'s `@type` before assuming which shape you got.
|
|
|
|
This page excludes the OAuth2/OIDC token-endpoint error format (`{"error": "invalid_request", ...}` from `/oauth/v2/token`, `/oauth/v2/introspect`, etc.), which follows [RFC 6749 §5.2](https://datatracker.ietf.org/doc/html/rfc6749#section-5.2) and is documented at the [OIDC endpoints reference](/apis/openidoauth/endpoints).
|
|
|
|
## How to use this reference
|
|
|
|
Every error ID is listed below, organized three levels deep — outward to inward, common to distinct:
|
|
|
|
1. **Subsystem** — the part of the backend that throws it (broadest: 8 groups)
|
|
2. **gRPC code** — the kind of failure: Not Found, Invalid Argument, Permission Denied, and so on
|
|
3. **Cause** — one entry per distinct underlying message. IDs that mean exactly the same thing (a validation check reused verbatim at several call sites) are merged into a single entry instead of repeated
|
|
|
|
That shape follows how the errors actually break down: there are only 8 subsystems and about a dozen gRPC codes, but roughly 1,150 genuinely distinct causes behind the ~3,200 individual IDs. **Use the search box** below to jump straight to an ID or a phrase — it matches across IDs, messages, and explanations, so it's usually faster than browsing the tree if you already have an ID or error text in hand.
|
|
|
|
Each entry shows why the error happens, an example response, and every source location it's thrown from. When the same ID string is also thrown for a *different* reason elsewhere, a warning links the two — the ID alone isn't sufficient to tell them apart, so check the message too.
|
|
|
|
<ErrorReference />
|