app/exceptions/base.py

"""Jerarquía de excepciones de la aplicación.

Cada excepción declara el código HTTP con el que debe responderse.
Los manejadores registrados en :mod:`app.core.exception_handlers` se
encargan de traducirlas a respuestas JSON consistentes.
"""

from __future__ import annotations


class AppException(Exception):
    """Excepción base para todos los errores controlados de la app."""

    status_code: int = 500
    detail: str = "Error interno del servidor."

    def __init__(self, detail: str | None = None) -> None:
        if detail is not None:
            self.detail = detail
        super().__init__(self.detail)


class NotFoundError(AppException):
    """El recurso solicitado no existe."""

    status_code = 404
    detail = "Recurso no encontrado."


class ConflictError(AppException):
    """Conflicto con el estado actual (p. ej. valor duplicado)."""

    status_code = 409
    detail = "El recurso ya existe o genera un conflicto."


class InvalidIdError(AppException):
    """El identificador proporcionado no es un ObjectId válido."""

    status_code = 400
    detail = "Identificador inválido."


class ValidationError(AppException):
    """Error de validación de reglas de negocio."""

    status_code = 422
    detail = "Los datos proporcionados no son válidos."


class AuthenticationError(AppException):
    """Credenciales ausentes o inválidas."""

    status_code = 401
    detail = "No autenticado."


class AuthorizationError(AppException):
    """El usuario no tiene permisos suficientes."""

    status_code = 403
    detail = "No tienes permisos para realizar esta acción."