Error Matrix By Status

Overview

How to mix shared COMMON_* errors with entity codes (e.g. USER_*), and how to review routers by HTTP status.

Rule of thumb

Use COMMON_* when the same error applies everywhere.
Use entity prefixes (USER_*, later CONTRACT_*, etc.) for domain-specific cases.
Never change the meaning of a published code + key pair.
Mirror declared responses in OpenAPI examples and tests.

Where to define reusable responses

app/errors/common.py and app/errors/user.py — one place for stable code, key, and default message (plus validation maps). Import here; do not copy strings.
app/openapi/responses.py - shared response blocks for routers.
app/openapi/examples/errors.py - OpenAPI example payloads (built from the catalog above).
app/api/v1/*.py - endpoint-level assembly of common + entity responses.

Service-wide common pool (recommended baseline)

HTTP status	Code(s)	Key(s)	Reuse scope
`401`	`COMMON_401`	`SECURITY_AUTH_REQUIRED`	All protected endpoints.
`413`	`COMMON_413`	`SECURITY_REQUEST_BODY_TOO_LARGE`	Endpoints that can receive oversized body.
`429`	`COMMON_429`	`SECURITY_RATE_LIMIT_EXCEEDED`	All endpoints behind rate limiting.
`409`	`COMMON_409`	`IDEMPOTENCY_KEY_REUSED_WITH_DIFFERENT_PAYLOAD`	Write endpoints with idempotency semantics.
`400`	`COMMON_400`	`IDEMPOTENCY_KEY_REQUIRED`	Write endpoints where idempotency key is required.

Entity matrix example: user

Endpoint	HTTP status	Class	Code prefix	Current examples
`POST /api/v1/user`	`400`	Mixed: COMMON + entity	`COMMON_` + `USER_`	`IDEMPOTENCY_KEY_REQUIRED`, `USER_CREATE_ALREADY_EXISTS`
`POST /api/v1/user`	`422`	Entity validation matrix	`USER_00x`	`USER_001...USER_013`
`GET /api/v1/user/{system_user_id}`	`404`	Entity business	`USER_*`	`USER_NOT_FOUND` (`USER_404`)
`PUT /api/v1/user/{system_user_id}`	`422`	Entity validation matrix	`USER_014…USER_024`	Update body rules (e.g. `USER_UPDATE_TIMEZONE_INVALID`)
`PATCH /api/v1/user/{system_user_id}`	`400`	Entity business	`USER_102`	`USER_PATCH_BODY_EMPTY` (no fields in body)
`PATCH /api/v1/user/{system_user_id}`	`422`	Entity validation matrix	`USER_014…USER_024`	Same field rules as PUT when a field is present
`GET /api/v1/user/{system_user_id}`	`401`, `429`	COMMON reusable	`COMMON_*`	Auth and rate-limit responses reused from shared pool

Router review checklist (status-first)

List all response statuses declared in router responses={...}.
Mark each status as COMMON or ENTITY.
Ensure COMMON statuses come from app/openapi/responses.py.
Ensure ENTITY statuses use entity-prefixed code space and mapped examples.
Validate with tests and make verify.

Related governance docs

Page history

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