"""Exception hierarchy for the Fireplace SDK."""

from __future__ import annotations

from typing import Any, Optional


class FireplaceError(Exception):
    """Base exception for all Fireplace SDK errors."""

    def __init__(
        self,
        message: str,
        *,
        status_code: Optional[int] = None,
        response_body: Optional[Any] = None,
    ) -> None:
        super().__init__(message)
        self.status_code = status_code
        self.response_body = response_body


class BadRequestError(FireplaceError):
    """400 — invalid parameters or malformed request."""


class AuthenticationError(FireplaceError):
    """401 — missing or invalid API keys."""


class ForbiddenError(FireplaceError):
    """403 — insufficient permissions for this endpoint."""


class RateLimitError(FireplaceError):
    """429 — rate limit exceeded (default 5 req/s).

    Attributes:
        retry_after: Seconds until the rate-limit window resets (from
            ``X-RateLimit-Reset``), or *None* if the header was absent.
    """

    def __init__(
        self,
        message: str,
        *,
        status_code: int = 429,
        response_body: Optional[Any] = None,
        retry_after: Optional[float] = None,
    ) -> None:
        super().__init__(
            message, status_code=status_code, response_body=response_body
        )
        self.retry_after = retry_after


class ServerError(FireplaceError):
    """5xx — an unexpected error on Fireplace's side."""
