# exceptions.py — Error types for the COS SDK.
#
# These exceptions give developers clear, actionable error messages
# when something goes wrong with their COS API calls.


class COSError(Exception):
    """Base exception for all COS SDK errors."""

    def __init__(self, message: str, status_code: int = None, response_body: dict = None):
        self.message = message
        self.status_code = status_code
        self.response_body = response_body or {}
        super().__init__(self.message)


class AuthenticationError(COSError):
    """Raised when the API key is missing, invalid, or revoked (401)."""
    pass


class ForbiddenError(COSError):
    """Raised when the API key doesn't have access to the requested tier (403)."""
    pass


class RateLimitError(COSError):
    """Raised when the API key has exceeded its rate limit (429)."""

    def __init__(self, message: str, retry_after: int = 60, **kwargs):
        self.retry_after = retry_after
        super().__init__(message, **kwargs)


class ValidationError(COSError):
    """Raised when the request is malformed (400)."""
    pass


class ServerError(COSError):
    """Raised when the COS server returns a 5xx error."""
    pass
