Errors

Response shape

Two envelope shapes are in play:

Most endpoints return the application result ServiceResult — { IsSuccess, Message, ErrorCode, ValidationErrors, Metadata } — so the machine-readable code is in ErrorCode and the human string in Message (e.g. the role codes below).
OAuth / OIDC endpoints follow the RFC shape — { error, error_description }.

ExceptionHandlingMiddleware maps exceptions to status codes: ValidationException / DomainValidationException → 400, DomainEntityNotFoundException → 404, OAuthSessionExpiredException → 401, UnauthorizedAccessException → 403, otherwise 500.

Status	Meaning
400	Validation / malformed request
401	Unauthenticated (missing/invalid token)
403	Authenticated but not permitted (e.g. not a member; `ORG_SEAL_REQUIRED`; tenant conflict)
404	Not found (or feature disabled)
409	Conflict (duplicate name/key, cycle)
500	Unhandled server error

Role & permission error codes

A representative set (RoleConstants.ErrorCodes):

Code	Meaning
`ROLE_NOT_FOUND`	Role does not exist
`ROLE_DUPLICATE_NAME` / `ROLE_DUPLICATE_KEY`	Name/key already used
`ROLE_SYSTEM_PROTECTED`	System roles can’t be modified/deleted
`ROLE_KEY_RESERVED`	Reserved role key
`ROLE_CIRCULAR_REFERENCE` / `ROLE_HIERARCHY_DEPTH_EXCEEDED`	Hierarchy violations
`ROLE_IN_USE` / `ROLE_LAST_ADMIN`	Can’t delete a role in use / the last admin role
`ROLE_INSUFFICIENT_PERMISSION`	Caller lacks permission
`ROLE_MUTUAL_EXCLUSION`	Conflicts with an assigned role (SoD)