GRPC Status Codes in ZITADEL | ZITADEL Docs
GRPC Status Codes in ZITADEL
| 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.