# -*- coding: utf-8 -*-
"""
Exception types for the CHARM SDK.

This module defines the various exception types that can be raised by the CHARM SDK.
These exceptions provide detailed information about what went wrong during API calls,
allowing for better error handling and debugging.
"""

class CharmError(Exception):
    """
    Base exception for CHARM SDK.
    
    All other exceptions in the SDK inherit from this class, allowing you to catch
    any CHARM-related exception with a single except clause.
    
    Example:
    --------
    >>> try:
    ...     response = client.embeddings.create(...)
    ... except CharmError as e:
    ...     print(f"CHARM error: {e}")
    """


class APIError(CharmError):
    """
    Server returned a 5xx or unexpected response.
    
    This exception is raised when the server returns a 5xx status code or any
    other unexpected response that doesn't match more specific error types.
    """


class RateLimitError(CharmError):
    """
    HTTP 429 / rate-limited.
    
    This exception is raised when the server returns a 429 status code,
    indicating that you've exceeded the rate limit for API calls.
    Consider implementing backoff and retry logic when handling this exception.
    """


class ServiceUnavailableError(CharmError):
    """
    HTTP 503 or service unavailable.
    
    This exception is raised when the server returns a 503 status code,
    indicating that the service is temporarily unavailable.
    """


class InvalidRequestError(CharmError):
    """
    HTTP 400 / validation error on the client request.
    
    This exception is raised when the server returns a 400 status code,
    indicating that there's an issue with the request parameters or format.
    Check the error message for details on what needs to be fixed.
    """


class AuthenticationError(CharmError):
    """
    HTTP 401/403 when auth is required or invalid.
    
    This exception is raised when authentication fails, either because no API key
    was provided or the provided key is invalid or expired.
    """


class TimeoutError_(CharmError):
    """
    Request timed out.
    
    This exception is raised when a request to the CHARM API times out.
    Consider increasing the timeout parameter when initializing the client
    if you're working with large datasets.
    """


class NetworkError(CharmError):
    """
    Connectivity or TLS issues.
    
    This exception is raised when there are network-related issues such as
    DNS resolution failures, connection refused, or TLS/SSL errors.
    """


class ResponseValidationError(CharmError):
    """
    The response payload didn't match the expected schema.
    
    This exception is raised when the server's response is not in the expected
    format, such as missing required fields or containing invalid data types.
    """