Exceptions¶

The exception hierarchy lives in website/exceptions/ and provides structured, domain-specific errors used throughout the service layer.

Hierarchy¶

QuestMasterError             # Base for all application errors
  +-- NotFoundError          # Resource not found
  +-- UnauthorizedError      # Permission denied
  +-- ValidationError        # Input validation failure
  +-- DatabaseError          # Database operation failure
  +-- DiscordError           # Discord integration base error
  |     +-- DiscordAPIError  # Discord API call failure
  +-- GameError              # Game-related base error
        +-- GameFullError          # Game has no open slots
        +-- GameClosedError        # Game is not accepting registrations
        +-- DuplicateRegistrationError  # User already registered
        +-- SessionConflictError        # Session time conflict

Usage¶

Services raise these exceptions. Views catch them and translate to appropriate HTTP responses.

from website.exceptions import GameFullError

def register_player(game_id: int, user: User) -> None:
    game = game_repo.get_by_id(game_id)
    if game.is_full:
        raise GameFullError(f"Game '{game.name}' is full")
    # ...

API Reference¶

Custom exception hierarchy for the QuestMaster application.

`NotFoundError` ¶

Bases: QuestMasterError

Resource not found.

Source code in website/exceptions/base.py

class NotFoundError(QuestMasterError):
    """Resource not found."""

    http_status = 404

    def __init__(self, message: str, resource_type=None, resource_id=None, **kwargs):
        kwargs.setdefault("code", "NOT_FOUND")
        details = kwargs.pop("details", {})
        if resource_type is not None:
            details["resource_type"] = resource_type
        if resource_id is not None:
            details["resource_id"] = resource_id
        super().__init__(message, details=details, **kwargs)

`QuestMasterError` ¶

Bases: Exception

Base exception for all QuestMaster errors.

Parameters:

Name	Type	Description	Default
`message`	`str`	Human-readable error description.	required
`code`	`str`	Machine-readable error code (e.g. "GAME_FULL").	`None`
`details`	`dict`	Additional context about the error.	`None`

Source code in website/exceptions/base.py

class QuestMasterError(Exception):
    """Base exception for all QuestMaster errors.

    Args:
        message: Human-readable error description.
        code: Machine-readable error code (e.g. "GAME_FULL").
        details: Additional context about the error.
    """

    http_status = None

    def __init__(self, message: str, code: str = None, details: dict = None):
        self.message = message
        self.code = code
        self.details = details or {}
        super().__init__(self.message)

    def to_dict(self):
        """Serialize the error for API responses."""
        result = {"error": self.message, "code": self.code}
        if self.details:
            result["details"] = self.details
        return result

    def __repr__(self):
        parts = [f"message={self.message!r}"]
        if self.code:
            parts.append(f"code={self.code!r}")
        if self.details:
            parts.append(f"details={self.details!r}")
        return f"{self.__class__.__name__}({', '.join(parts)})"

`to_dict()` ¶

Serialize the error for API responses.

Source code in website/exceptions/base.py

def to_dict(self):
    """Serialize the error for API responses."""
    result = {"error": self.message, "code": self.code}
    if self.details:
        result["details"] = self.details
    return result

`UnauthorizedError` ¶

Bases: QuestMasterError

User not authorized to perform this action.

Source code in website/exceptions/base.py

class UnauthorizedError(QuestMasterError):
    """User not authorized to perform this action."""

    http_status = 403

    def __init__(self, message: str, user_id=None, action=None, **kwargs):
        kwargs.setdefault("code", "UNAUTHORIZED")
        details = kwargs.pop("details", {})
        if user_id is not None:
            details["user_id"] = user_id
        if action is not None:
            details["action"] = action
        super().__init__(message, details=details, **kwargs)