from __future__ import annotations


class Gamma23Error(Exception):
    """Base exception for all Gamma23 API errors."""

    def __init__(
        self,
        message: str,
        *,
        status_code: int | None = None,
        code: str | None = None,
        request_id: str | None = None,
    ) -> None:
        super().__init__(message)
        self.message = message
        self.status_code = status_code
        self.code = code
        self.request_id = request_id

    def __repr__(self) -> str:
        parts = [f"message={self.message!r}"]
        if self.status_code is not None:
            parts.append(f"status_code={self.status_code}")
        if self.code is not None:
            parts.append(f"code={self.code!r}")
        if self.request_id is not None:
            parts.append(f"request_id={self.request_id!r}")
        return f"Gamma23Error({', '.join(parts)})"

    def __str__(self) -> str:
        s = self.message
        if self.status_code is not None:
            s = f"[{self.status_code}] {s}"
        if self.code is not None:
            s = f"{s} (code: {self.code})"
        if self.request_id is not None:
            s = f"{s} [request_id: {self.request_id}]"
        return s


class AuthenticationError(Gamma23Error):
    """Raised when the API key is invalid or missing."""


class RateLimitError(Gamma23Error):
    """Raised when the API rate limit is exceeded."""


class NotFoundError(Gamma23Error):
    """Raised when a requested resource is not found."""


class ValidationError(Gamma23Error):
    """Raised when the request fails server-side validation."""
