Errors
Response shape
Section titled “Response shape”Errors return a JSON body with an error (and often a human-readable error_description or detail). HTTP status conventions:
| 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) |
Role & permission error codes
Section titled “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) |