Error Matrix

Overview

Error handling in this project is treated as a contract, defined by stable code and key pairs. See the policy in ADR 0003.

Approach: All errors are identified by a unique code and key combination (For example:COMMON_*, USER_*). This enables automated tracking and backward-compatible evolution.
Source of truth: Error definitions live in app/errors/; example responses are in app/openapi/examples/errors.py; response schemas are defined in app/schemas/errors.py.
Sync mechanism: This page uses marker blocks, partially generated by scripts/sync_docs.py. To update documentation after error changes, run make docs-fix to refresh all associated tables.

COMMON catalog

Show COMMON error table

Code	Key	Message	Defined in
`COMMON_000`	`COMMON_VALIDATION_ERROR`	Request validation failed.	`app/errors/common.py`
`COMMON_400`	`IDEMPOTENCY_KEY_REQUIRED`	Missing required `Idempotency-Key` header for write operation.	`app/errors/common.py`
`COMMON_401`	`SECURITY_AUTH_REQUIRED`	Missing or invalid API key in header `X-API-Key`.	`app/errors/common.py`
`COMMON_409`	`IDEMPOTENCY_KEY_REUSED_WITH_DIFFERENT_PAYLOAD`	Idempotency key was already used with another payload.	`app/errors/common.py`
`COMMON_413`	`SECURITY_REQUEST_BODY_TOO_LARGE`	Request body exceeds configured maximum size.	`app/errors/common.py`
`COMMON_429`	`SECURITY_RATE_LIMIT_EXCEEDED`	Too many requests. Retry later.	`app/errors/common.py`
`COMMON_500`	`SECURITY_AUTH_STRATEGY_INVALID`	Unsupported API authentication configuration.	`app/errors/common.py`

USER catalog

Show USER error table

Code	Key	Message	Defined in
`USER_001`	`USER_CREATE_SYSTEM_USER_ID_REQUIRED`	Field `system_user_id` is required.	`app/errors/user.py`
`USER_002`	`USER_CREATE_SYSTEM_USER_ID_INVALID`	Field `system_user_id` must not be empty.	`app/errors/user.py`
`USER_003`	`USER_CREATE_FULL_NAME_REQUIRED`	Field `full_name` is required.	`app/errors/user.py`
`USER_004`	`USER_CREATE_FULL_NAME_TOO_SHORT`	Field `full_name` must not be empty.	`app/errors/user.py`
`USER_005`	`USER_CREATE_FULL_NAME_TOO_LONG`	Field `full_name` exceeds max length.	`app/errors/user.py`
`USER_006`	`USER_CREATE_USERNAME_TOO_LONG`	Field `username` exceeds max length.	`app/errors/user.py`
`USER_007`	`USER_CREATE_TIMEZONE_INVALID`	Field `timezone` must be a valid IANA timezone.	`app/errors/user.py`
`USER_008`	`USER_CREATE_TIMEZONE_TOO_LONG`	Field `timezone` exceeds max length.	`app/errors/user.py`
`USER_009`	`USER_CREATE_SYSTEM_UUID_INVALID`	Field `system_uuid` must be a valid UUID.	`app/errors/user.py`
`USER_010`	`USER_CREATE_INVALIDATION_REASON_UUID_INVALID`	Field `invalidation_reason_uuid` must be a valid UUID.	`app/errors/user.py`
`USER_011`	`USER_CREATE_IS_ROW_INVALID_TYPE`	Field `is_row_invalid` must be an integer.	`app/errors/user.py`
`USER_012`	`USER_CREATE_IS_ROW_INVALID_MIN`	Field `is_row_invalid` must be >= 0.	`app/errors/user.py`
`USER_013`	`USER_CREATE_IS_ROW_INVALID_MAX`	Field `is_row_invalid` must be <= 1.	`app/errors/user.py`
`USER_014`	`USER_UPDATE_FULL_NAME_REQUIRED`	Field `full_name` is required.	`app/errors/user.py`
`USER_015`	`USER_UPDATE_FULL_NAME_TOO_SHORT`	Field `full_name` must not be empty.	`app/errors/user.py`
`USER_016`	`USER_UPDATE_FULL_NAME_TOO_LONG`	Field `full_name` exceeds max length.	`app/errors/user.py`
`USER_017`	`USER_UPDATE_USERNAME_TOO_LONG`	Field `username` exceeds max length.	`app/errors/user.py`
`USER_018`	`USER_UPDATE_TIMEZONE_INVALID`	Field `timezone` must be a valid IANA timezone.	`app/errors/user.py`
`USER_019`	`USER_UPDATE_TIMEZONE_TOO_LONG`	Field `timezone` exceeds max length.	`app/errors/user.py`
`USER_020`	`USER_UPDATE_SYSTEM_UUID_INVALID`	Field `system_uuid` must be a valid UUID.	`app/errors/user.py`
`USER_021`	`USER_UPDATE_INVALIDATION_REASON_UUID_INVALID`	Field `invalidation_reason_uuid` must be a valid UUID.	`app/errors/user.py`
`USER_022`	`USER_UPDATE_IS_ROW_INVALID_TYPE`	Field `is_row_invalid` must be an integer.	`app/errors/user.py`
`USER_023`	`USER_UPDATE_IS_ROW_INVALID_MIN`	Field `is_row_invalid` must be >= 0.	`app/errors/user.py`
`USER_024`	`USER_UPDATE_IS_ROW_INVALID_MAX`	Field `is_row_invalid` must be <= 1.	`app/errors/user.py`
`USER_025`	`USER_CREATE_SYSTEM_UUID_REQUIRED`	Field `system_uuid` is required.	`app/errors/user.py`
`USER_101`	`USER_CREATE_ALREADY_EXISTS`	User with this `system_user_id` and `system_uuid` already exists.	`app/errors/user.py`
`USER_102`	`USER_PATCH_BODY_EMPTY`	PATCH body must include at least one field to update.	`app/errors/user.py`
`USER_404`	`USER_NOT_FOUND`	User with this `system_user_id` and `system_uuid` was not found.	`app/errors/user.py`

Synchronization mechanism

Define or update stable errors in app/errors/common.py and app/errors/user.py.
Update OpenAPI examples in app/openapi/examples/errors.py and router responses.
Run make docs-fix (calls scripts/sync_docs.py).
The script patches marker blocks on this page, so catalog tables stay code-driven.
Run make docs-check / make verify before merge.

Page history

Date	Change	Author
2026-04-21	Added Page history section (repository baseline).	Ivan Boyarkin