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
+3 -1
View File
@@ -1,6 +1,8 @@
package zerrors
import "fmt"
import (
"fmt"
)
func ThrowPermissionDenied(parent error, id, message string) error {
return CreateZitadelError(KindPermissionDenied, parent, id, message, 1)
+36
View File
@@ -1,6 +1,8 @@
package zerrors
import (
"bytes"
"encoding/json"
"errors"
"fmt"
"log/slog"
@@ -111,6 +113,7 @@ type ZitadelError struct {
Parent error
Message string
ID string
Details ErrorDetails
// location where the error was created
reportLocation *sloggcp.ReportLocation
@@ -119,6 +122,16 @@ type ZitadelError struct {
hasStackTrace bool
}
type Slug string
type ErrorDetails json.Marshaler
type ErrorDetailsMap map[string]any
func (m ErrorDetailsMap) MarshalJSON() ([]byte, error) {
return json.Marshal(map[string]any(m))
}
func ThrowError(parent error, id, message string) error {
return CreateZitadelError(KindUnknown, parent, id, message, 1)
}
@@ -183,6 +196,15 @@ func (err *ZitadelError) GetID() string {
return err.ID
}
func (err *ZitadelError) GetDetails() ErrorDetails {
return err.Details
}
func (err *ZitadelError) WithDetails(details ErrorDetails) *ZitadelError {
err.Details = details
return err
}
func (err *ZitadelError) Is(target error) bool {
t, ok := target.(*ZitadelError)
if !ok {
@@ -200,6 +222,20 @@ func (err *ZitadelError) Is(target error) bool {
if t.Parent != nil && !errors.Is(err.Parent, t.Parent) {
return false
}
if t.Details != nil {
if err.Details == nil {
return false
}
targetData, detailsErr := t.Details.MarshalJSON()
if detailsErr != nil {
return false
}
errData, detailsErr := err.Details.MarshalJSON()
if detailsErr != nil {
return false
}
return bytes.Equal(targetData, errData)
}
return true
}