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]>
34 lines
5.2 KiB
Plaintext
34 lines
5.2 KiB
Plaintext
---
|
|
title: GRPC Status Codes in ZITADEL
|
|
description: "Mapping of gRPC status codes to their corresponding HTTP status codes in ZITADEL API responses."
|
|
sidebar_label: GRPC Status Codes
|
|
---
|
|
|
|
| GRPC Number | GRPC Code | HTTP Status Code | HTTP Status Text | Description |
|
|
|:------------|:--------------------|------------------|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
| 0 | OK | 200 | OK | Not an error; returned on success. |
|
|
| 2 | UNKNOWN | 500 | Internal | Unknown error, this is sent if the error could not be identified as one of the errors described below |
|
|
| 3 | INVALID_ARGUMENT | 400 | Bad Request | The client specified an invalid argument. Note that this differs from FAILED_PRECONDITION. INVALID_ARGUMENT indicates arguments that are problematic regardless of the state of the system (e.g., a malformed file name). |
|
|
| 4 | DEADLINE_EXCEEDED | 504 | Gateway Timeout | The deadline expired before the operation could complete. |
|
|
| 5 | NOT_FOUND | 404 | Not found | Some requested entity (e.g. user or project) was not found. |
|
|
| 6 | ALREADY_EXISTS | 409 | Conflict | The entity that a client attempted to create (e.g. user or project) already exists. |
|
|
| 7 | PERMISSION_DENIED | 403 | Forbidden | The caller does not have permission to execute the specified operation. |
|
|
| 9 | FAILED_PRECONDITION | 400 | Bad Request | The operation was rejected because the system is not in a state required for the operation's execution. e.g a project that is already deactivated, should be deactivated |
|
|
| 12 | UNIMPLEMENTED | 501 | Not Implemented | The operation is not implemented or is not supported/enabled in this service. |
|
|
| 13 | INTERNAL | 500 | Internal | Internal errors. This means that some invariants expected by the underlying system have been broken. This error code is reserved for serious errors. |
|
|
| 14 | UNAVAILABLE | 503 | Service Unavailable | The service is currently unavailable. |
|
|
| 16 | UNAUTHENTICATED | 401 | Unauthorized | The request does not have valid authentication credentials for the operation. |
|
|
|
|
## Error details and slugs
|
|
|
|
For stable `v2` APIs, services import `zitadel/error/v2/error.proto` so reflection-aware clients can resolve `zitadel.error.v2.ErrorDetail`.
|
|
|
|
When present, inspect `ErrorDetail.slug` first for programmatic handling. Slugs are stable machine-readable identifiers such as `user.already_exists`.
|
|
|
|
Use `ErrorDetail.message` for developer diagnostics, not end-user text. Prefer mapping slugs to your own localized messages in clients.
|
|
|
|
This slug-based handling is currently relevant for backend/domain paths that run with relational-storage-backed logic.
|
|
Do not assume it for `v1`, `v2beta`, or `v3alpha` APIs or when using a v2 endpoint without having the relational storage feature enabled.
|
|
|
|
For a searchable catalog of every `details[].id` ZITADEL can return — grouped by subsystem and cause, with why each one happens and an example response — see the [Error Reference](/apis/errors).
|