Source code for cleancsv.errors

"""Exceptions raised by the CleanCSV Python client."""

from __future__ import annotations




class CleanCSVError(Exception):
    """Error returned by the CleanCSV API or raised for failed HTTP responses.

    Subclass of :exc:`Exception` carrying the HTTP status and response body when
    available so callers can log or display API error messages.

    Attributes:
        status_code: HTTP status code if the error came from a response, else ``None``.
        body: Raw response body text when available (may be HTML or JSON string).
    """

    def __init__(self, message: str, status_code: int | None = None, body: str | None = None) -> None:
        """Initialize the error.

        Args:
            message: Human-readable error message (often from JSON ``error`` or body).
            status_code: HTTP status code from the failed response, if applicable.
            body: Full response body as text for debugging.
        """
        super().__init__(message)
        self.status_code = status_code
        self.body = body





class RateLimitError(CleanCSVError):
    """Rate limit exceeded (HTTP 429), typically on demo or throttled endpoints.

    Extends :class:`CleanCSVError` with optional metadata from response headers or
    JSON so clients can back off or retry.

    Attributes:
        remaining: Remaining quota from ``X-RateLimit-Remaining`` or JSON, if parsed.
        reset_ms: Reset time in milliseconds from JSON ``reset``, if present.
        retry_after_s: Suggested retry delay in seconds from ``Retry-After``, if present.
        body: Inherited from :class:`CleanCSVError` — raw response body text.
        status_code: Always ``429`` for this exception type.
    """

    def __init__(
        self,
        message: str,
        *,
        remaining: int | None = None,
        reset_ms: int | None = None,
        retry_after_s: int | None = None,
        body: str | None = None,
    ) -> None:
        """Initialize a rate-limit error.

        Args:
            message: Error message (from API or generic text).
            remaining: Optional remaining request count before limit.
            reset_ms: Optional epoch or window reset time in milliseconds (API-specific).
            retry_after_s: Optional seconds to wait before retrying (``Retry-After``).
            body: Raw response body for debugging.
        """
        super().__init__(message, status_code=429, body=body)
        self.remaining = remaining
        self.reset_ms = reset_ms
        self.retry_after_s = retry_after_s