Exceptions#

HTTP client exception hierarchy for the core_https library.

This module provides a comprehensive set of exception classes for handling HTTP-related errors in a structured and consistent manner. The exception hierarchy is designed to allow for fine-grained error handling while maintaining compatibility with standard HTTP status codes.

Exception Hierarchy:

Exception
└── InternalServerError (base for all HTTP errors)
    ├── ServiceException (handled service errors)
    │   ├── AuthenticationException (401 Unauthorized)
    │   ├── AuthorizationException (403 Forbidden)
    │   └── RateLimitException (429 Too Many Requests)
    └── RetryableException (errors that should trigger retries)

Usage Example:

Basic exception handling:

from core_https.exceptions import AuthenticationException, RateLimitException

try:
    response = requester.request(url="https://api.example.com")
except AuthenticationException as e:
    logger.error(f"Authentication failed: {e.details}")
    # Handle authentication error
except RateLimitException as e:
    logger.warning(f"Rate limited: {e.details}")
    # Implement backoff strategy
except ServiceException as e:
    logger.error(f"Service error {e.status_code}: {e.details}")
    # Handle other service errors

Error information extraction:

try:
    # HTTP request that fails
    pass
except InternalServerError as e:
    error_info = e.get_error_info()
    # {'type': 'AuthenticationException', 'details': 'Invalid API key'}

See also

core_https.requesters.base.IRequester: Base requester that raises these exceptions
HTTP status codes: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status

class core_https.exceptions.ErrorInfo[source]#

Bases: TypedDict

Structured error payload returned by InternalServerError.get_error_info().

type: str#

details: str#

exception core_https.exceptions.InternalServerError(status_code: int, details: str, *args)[source]#

Bases: Exception

Base class for all HTTP-related exceptions in the core_https library.

This exception serves as the root of the HTTP exception hierarchy and handles unhandled errors that occur during HTTP operations. It provides structured error information including HTTP status codes and detailed error messages.

status_code#: HTTP status code associated with the error

details#: Detailed error message or description

__init__(status_code: int, details: str, *args) → None[source]#

get_error_info() → ErrorInfo[source]#: Get structured error information for logging or serialization. :returns: Dictionary containing error type and details.

exception core_https.exceptions.ServiceException(status_code: int, details: str, *args)[source]#

Bases: InternalServerError

Exception caused for handled errors within the service

exception core_https.exceptions.AuthenticationException(status_code: int = 401, details: str = 'Unauthorized')[source]#

Bases: ServiceException

Exception caused for authentication [401] issues

__init__(status_code: int = 401, details: str = 'Unauthorized') → None[source]#

exception core_https.exceptions.AuthorizationException(status_code: int = 403, details: str = 'Forbidden')[source]#

Bases: ServiceException

Exception caused for authorization [403] issues

__init__(status_code: int = 403, details: str = 'Forbidden') → None[source]#

exception core_https.exceptions.RateLimitException(status_code: int = 429, details: str = 'Too Many Requests')[source]#

Bases: ServiceException

Exception caused [429] when a client has sent too many requests to a server within a given time frame.

__init__(status_code: int = 429, details: str = 'Too Many Requests') → None[source]#

exception core_https.exceptions.RetryableException(status_code: int, details: str, *args)[source]#

Bases: InternalServerError

Exception for HTTP errors that should trigger retry mechanisms.

This exception represents temporary failures that are likely to succeed if retried after a short delay. Common retryable status codes include: - 429 Too Many Requests (rate limiting) - 502 Bad Gateway (temporary server issue) - 503 Service Unavailable (server overload) - 504 Gateway Timeout (temporary timeout)

Example

raise RetryableException(status_code=503, details=”Service temporarily unavailable”) raise RetryableException(status_code=502, details=”Bad gateway from upstream”)

Exceptions#

This Page