"""Application error hierarchy → one consistent JSON error envelope.""" from typing import Any class AppError(Exception): """Base for every error the application raises deliberately.""" status_code: int = 400 code: str = "APP_ERROR" def __init__(self, message: str, details: dict[str, Any] | None = None) -> None: self.message = message self.details = details or {} super().__init__(message) def to_dict(self) -> dict[str, Any]: return { "error": { "code": self.code, "message": self.message, "details": self.details, } } class NotFoundError(AppError): status_code = 404 code = "NOT_FOUND" class ForbiddenError(AppError): """Raised for both role failures and data-scope failures. Deliberately 403 and not 404: the negative-scope tests (X1-X3) assert 403, so a scope bug cannot hide behind an ambiguous "not found". """ status_code = 403 code = "FORBIDDEN" class UnauthorizedError(AppError): status_code = 401 code = "UNAUTHORIZED" class ConflictError(AppError): status_code = 409 code = "CONFLICT" class ValidationError(AppError): status_code = 422 code = "VALIDATION_ERROR" class InvalidStateTransitionError(AppError): status_code = 409 code = "INVALID_STATE_TRANSITION" class ReportLockedError(AppError): """V10 — an APPROVED report can never be modified by any role.""" status_code = 409 code = "REPORT_LOCKED"