admin/_docs/02_document/modules/common_business_exception.md

Module: Azaion.Common.BusinessException

Purpose

Custom exception type for domain-level errors, paired with an ExceptionEnum catalog of all business error codes.

Public Interface

BusinessException

Member	Signature	Description
Constructor	BusinessException(ExceptionEnum exEnum)	Creates exception with message from ExceptionEnum's [Description] attribute
ExceptionEnum	ExceptionEnum ExceptionEnum { get; set; }	The specific error code
GetMessage	static string GetMessage(ExceptionEnum exEnum)	Looks up human-readable message for an error code

ExceptionEnum

Value	Code	Description	HTTP Status
NoEmailFound	10	No such email found	409
EmailExists	20	Email already exists	409
WrongPassword	30	Passwords do not match	409
PasswordLengthIncorrect	32	Password should be at least 12 characters	409
EmailLengthIncorrect	35	Email is empty or invalid	409
WrongEmail	37	(no description attribute)	409
UserDisabled	38	User account is disabled	409
AccountLocked	50	AZ-537 — account temporarily locked due to too many failed login attempts (carries RetryAfterSeconds)	423 Locked
LoginRateLimited	51	AZ-537 — too many login attempts per account; try again later (carries RetryAfterSeconds)	429 Too Many Requests
InvalidRefreshToken	52	AZ-531 — refresh token invalid / expired / revoked / reuse-detected	401 Unauthorized
SessionNotFound	53	AZ-535 — admin tried to revoke a non-existent session	404 Not Found
InvalidMissionRequest	54	AZ-533 — mission_id pattern fail or planned_duration_h out of bounds	400 Bad Request
AircraftNotFound	55	AZ-533 — aircraft id missing or not a CompanionPC user	400 Bad Request
MfaAlreadyEnabled	56	AZ-534 — /users/me/mfa/enroll called for a user that already has MFA on	409 Conflict
MfaNotEnrolling	57	AZ-534 — confirm called without a prior enroll	409 Conflict
MfaNotEnabled	58	AZ-534 — disable / verify-for-login called for a user without MFA	409 Conflict
InvalidMfaCode	59	AZ-534 — TOTP code (and recovery code) failed to verify	401 Unauthorized
NoFileProvided	60	No file provided	409
InvalidMfaToken	61	AZ-534 — step-1 MFA token failed to validate (signature / audience / expiry)	401 Unauthorized

RetryAfterSeconds

Member	Type	Description
Constructor	BusinessException(ExceptionEnum exEnum, int retryAfterSeconds)	Cycle 2 (AZ-537) — sets RetryAfterSeconds, surfaced by BusinessExceptionHandler as a Retry-After response header. Used by AccountLocked (returns remaining lockout seconds) and LoginRateLimited (returns the window seconds).
RetryAfterSeconds	int?	Optional cooldown hint; null when the exception was constructed without a window.

Cycle 1 (2026-05-13) note — HardwareIdMismatch = 40 and BadHardware = 45 were removed by AZ-197. Codes 40 and 45 should NOT be reused.

Cycle 2 (2026-05-14) note — WrongResourceName = 50 was removed early in the cycle along with the GetResourceRequest validator. The integer 50 has since been reused for AccountLocked as part of AZ-537 (since the previous user-facing string "Wrong resource name" is no longer surfaced anywhere). This is the one deliberate exception to the "gap kept" lesson — the old code had no remaining client surface and the auth modernization wanted a tightly-clustered range of new codes.

Internal Logic

Static constructor eagerly loads all ExceptionEnum descriptions into a dictionary via EnumExtensions.GetDescriptions<ExceptionEnum>(). Messages are retrieved by dictionary lookup with fallback to ToString(). The two-arg constructor sets RetryAfterSeconds for the lockout / rate-limit paths.

Dependencies

• EnumExtensions — for GetDescriptions<T>()

Consumers

• BusinessExceptionHandler — catches and maps via MapStatusCode. The default mapping is 409; cycle 2 codes use a per-enum status map (AccountLocked → 423, LoginRateLimited → 429, refresh/MFA validation failures → 401, SessionNotFound → 404, mission validation failures → 400, MFA conflict states → 409). When RetryAfterSeconds > 0 the handler also stamps a Retry-After response header.
• UserService — throws for the auth path (NoEmailFound, WrongPassword, EmailExists, UserDisabled, AccountLocked, LoginRateLimited)
• RefreshTokenService — throws InvalidRefreshToken on bad/expired/reuse-detected
• SessionService — throws SessionNotFound for admin-revoke of missing sids
• MissionTokenService — throws InvalidMissionRequest, AircraftNotFound
• MfaService — throws MfaAlreadyEnabled, MfaNotEnrolling, MfaNotEnabled, InvalidMfaCode, InvalidMfaToken, NoEmailFound, WrongPassword
• ResourcesService — throws NoFileProvided for missing file uploads
• Program.cs ParseSidClaim / ParseUserIdClaim helpers — throw InvalidRefreshToken (401) on missing or malformed claims
• FluentValidation validators — reference ExceptionEnum codes in .WithErrorCode()

Data Models

None.

Configuration

None.

External Integrations

None.

Security

Error codes are returned to the client via BusinessExceptionHandler along with the per-enum HTTP status. The Retry-After header on lockout / rate-limit responses lets well-behaved clients back off without blind retries.

Tests

None.