feat(domain): introduce error slugs (#12030)

# Which Problems Are Solved

As part of https://github.com/zitadel/zitadel/issues/11917 we want to
introduce error slugs so (API) clients can rely on stable,
machine-readable errors and act accordingly.

# How the Problems Are Solved

- Added a `NewSlug` helper function in the domain package.
- Added `ErrorDetails` to the `ZitadelError`
- Added an `zitadel.error.v2.ErrorDetail` proto message
- Updated the connectRPC error interceptor to map new slug based errors
to the new `ErrorDetail`
- Defined some common slugs and error functions like internal errors
- Defined (session) specific slugs used in the `DeleteSession` and
`CheckUser` functions and replaced old implementations
- Updated integration tests to check specific errors if the relation
database feature is enabled
- Updated doc and guideline to reflect the latest changes and decisions
- Updated DeleteSession endpoint API to list possible slugs

# Additional Changes

None

# Additional Context

- closes #11957

---------

Co-authored-by: Wim Van Laer <[email protected]>
This commit is contained in:
Livio Spring
2026-04-13 09:47:04 +02:00
committed by GitHub
co-authored by Wim Van Laer
parent 5c9361f6c7
commit a2bf528ca0
18 changed files with 524 additions and 97 deletions
+6
View File
@@ -226,6 +226,12 @@ Please check out the dedicated [API guidelines](./API_DESIGN.md) page when contr
To start developing, make sure you followed the [quick start](#quick-start) steps.
> [!IMPORTANT]
> For stable `v2` API services, add `import "zitadel/error/v2/error.proto";` to each `*_service.proto`.
> This enables reflection-aware clients to resolve `zitadel.error.v2.ErrorDetail` and use the `slug` field for programmatic handling.
> Scope note: this is relevant for backend/domain flows that run with relational-storage-backed logic.
> Do not apply this to `v1`, `v2beta`, or `v3alpha` APIs.
> [!IMPORTANT]
> The relational database migrations are work in progress on main. Therefore they are objectives to change. To simplify the development process you can add the following configuration to your setup step config (`--steps /path/to/config.yaml`). This re-initiates the relational tables on each restart.