app/utils/exceptions.py

"""
Custom exceptions for VoiceAuth API.

Provides specific exception types for different error scenarios.
"""


class VoiceAuthError(Exception):
    """Base exception for all VoiceAuth errors."""

    def __init__(self, message: str, details: dict | None = None) -> None:
        """
        Initialize VoiceAuthError.

        Args:
            message: Human-readable error message
            details: Additional error details
        """
        super().__init__(message)
        self.message = message
        self.details = details or {}


class AudioDecodeError(VoiceAuthError):
    """
    Raised when Base64 audio decoding fails.

    This typically occurs when:
    - The input is not valid Base64
    - The decoded data is corrupted
    """

    pass


class AudioFormatError(VoiceAuthError):
    """
    Raised when audio format is invalid or unsupported.

    This typically occurs when:
    - The audio is not a valid MP3 file
    - The audio codec is unsupported
    - The file header is corrupted
    """

    pass


class AudioDurationError(VoiceAuthError):
    """
    Raised when audio duration is out of allowed bounds.

    This typically occurs when:
    - Audio is shorter than minimum duration
    - Audio is longer than maximum duration
    """

    def __init__(
        self,
        message: str,
        duration: float | None = None,
        min_duration: float | None = None,
        max_duration: float | None = None,
    ) -> None:
        """
        Initialize AudioDurationError.

        Args:
            message: Human-readable error message
            duration: Actual duration of the audio
            min_duration: Minimum allowed duration
            max_duration: Maximum allowed duration
        """
        details = {}
        if duration is not None:
            details["duration"] = duration
        if min_duration is not None:
            details["min_duration"] = min_duration
        if max_duration is not None:
            details["max_duration"] = max_duration
        super().__init__(message, details)


class AudioProcessingError(VoiceAuthError):
    """
    Raised when audio processing fails.

    This is a general error for audio processing issues
    that don't fit into more specific categories.
    """

    pass


class ModelNotLoadedError(VoiceAuthError):
    """
    Raised when attempting to use an unloaded model.

    This typically occurs when:
    - The model failed to load on startup
    - The model was unloaded due to memory pressure
    """

    pass


class InferenceError(VoiceAuthError):
    """
    Raised when ML model inference fails.

    This typically occurs when:
    - The input tensor is malformed
    - GPU memory is exhausted
    - Model internal error
    """

    pass