Exceptions

Custom exceptions for the folioclient package.

This module provides FOLIO-specific exceptions that wrap httpx exceptions to give meaningful error context for library management system operations.

exception folioclient.exceptions.FolioError

Bases: Exception

Base exception for all FOLIO-related errors.

exception folioclient.exceptions.FolioClientClosed(message: str = 'The FolioClient is closed')

Bases: FolioError

Raised when an operation is attempted on a closed FolioClient.

__init__(message: str = 'The FolioClient is closed') → None

exception folioclient.exceptions.FolioConnectionError(message: str, *, request: Request)

Bases: FolioError, RequestError

Base class for FOLIO connection-related errors. Raised when there are network connectivity issues with the FOLIO system.

__init__(message: str, *, request: Request) → None

exception folioclient.exceptions.FolioSystemUnavailableError(message: str, *, request: Request)

Bases: FolioConnectionError

Raised when the FOLIO system is completely unreachable. This indicates the FOLIO instance, API gateway, or module is down.

exception folioclient.exceptions.FolioTimeoutError(message: str, *, request: Request)

Bases: FolioConnectionError, TimeoutException

Raised when requests to FOLIO time out. Could indicate slow FOLIO modules, database issues, or network problems.

exception folioclient.exceptions.FolioProtocolError(message: str, *, request: Request)

Bases: FolioConnectionError

Raised when there are HTTP protocol-level errors with FOLIO. Could indicate API gateway issues or module communication problems.

exception folioclient.exceptions.FolioNetworkError(message: str, *, request: Request)

Bases: FolioConnectionError

Raised for general network connectivity issues with FOLIO. DNS resolution failures, connection refused, etc.

exception folioclient.exceptions.FolioHTTPError(message: str, *, request: Request, response: Response)

Bases: FolioError, HTTPStatusError

Base class for FOLIO HTTP status errors.

__init__(message: str, *, request: Request, response: Response) → None

exception folioclient.exceptions.FolioClientError(message: str, *, request: Request, response: Response)

Bases: FolioHTTPError

Base class for 4xx client errors from FOLIO. Indicates issues with the request format, authentication, or permissions.

exception folioclient.exceptions.FolioAuthenticationError(message: str = 'Authentication failed - invalid credentials or expired token', *, request: Request, response: Response)

Bases: FolioClientError

Raised for 401 authentication failures with FOLIO. Invalid credentials, expired tokens, or authentication module issues.

__init__(message: str = 'Authentication failed - invalid credentials or expired token', *, request: Request, response: Response) → None

exception folioclient.exceptions.FolioPermissionError(message: str = 'Permission denied - insufficient FOLIO permissions', *, request: Request, response: Response)

Bases: FolioClientError

Raised for 403 permission denied errors. User lacks required FOLIO permissions for the requested operation.

__init__(message: str = 'Permission denied - insufficient FOLIO permissions', *, request: Request, response: Response) → None

exception folioclient.exceptions.FolioResourceNotFoundError(message: str = 'Resource not found - FOLIO record or endpoint missing for the request', *, request: Request, response: Response)

Bases: FolioClientError

Raised for 404 not found errors. FOLIO resource specified (user, item, instance, etc.) or endpoint doesn’t exist for the specified HTTP method.

__init__(message: str = 'Resource not found - FOLIO record or endpoint missing for the request', *, request: Request, response: Response) → None

exception folioclient.exceptions.FolioDataConflictError(message: str = 'Data conflict - record may have been modified or duplicated', *, request: Request, response: Response)

Bases: FolioClientError

Raised for 409 conflict errors. Data conflicts like duplicate records, optimistic locking failures, or constraint violations.

__init__(message: str = 'Data conflict - record may have been modified or duplicated', *, request: Request, response: Response) → None

exception folioclient.exceptions.FolioValidationError(message: str = "Validation failed - data doesn't meet FOLIO requirements", *, request: Request, response: Response)

Bases: FolioClientError

Raised for 422 validation errors. Data doesn’t meet FOLIO schema requirements or business rules.

__init__(message: str = "Validation failed - data doesn't meet FOLIO requirements", *, request: Request, response: Response) → None

exception folioclient.exceptions.FolioRateLimitError(message: str = 'Rate limit exceeded - too many requests to FOLIO', *, request: Request, response: Response)

Bases: FolioClientError

Raised for 429 rate limiting errors. Too many requests to FOLIO in a given time period.

__init__(message: str = 'Rate limit exceeded - too many requests to FOLIO', *, request: Request, response: Response) → None

exception folioclient.exceptions.FolioBadRequestError(message: str = 'Bad request - malformed request or invalid parameters', *, request: Request, response: Response)

Bases: FolioClientError

Raised for 400 bad request errors. Malformed request syntax or invalid parameters.

__init__(message: str = 'Bad request - malformed request or invalid parameters', *, request: Request, response: Response) → None

exception folioclient.exceptions.FolioServerError(message: str, *, request: Request, response: Response)

Bases: FolioHTTPError

Base class for 5xx server errors from FOLIO. Indicates problems within the FOLIO system itself.

exception folioclient.exceptions.FolioInternalServerError(message: str = 'Internal server error - unexpected FOLIO system error', *, request: Request, response: Response)

Bases: FolioServerError

Raised for 500 internal server errors. Unexpected errors within FOLIO modules or API gateway.

__init__(message: str = 'Internal server error - unexpected FOLIO system error', *, request: Request, response: Response) → None

exception folioclient.exceptions.FolioBadGatewayError(message: str = 'Bad gateway - invalid response from FOLIO module', *, request: Request, response: Response)

Bases: FolioServerError

Raised for 502 bad gateway errors. API gateway received invalid response from a FOLIO module.

__init__(message: str = 'Bad gateway - invalid response from FOLIO module', *, request: Request, response: Response) → None

exception folioclient.exceptions.FolioServiceUnavailableError(message: str = 'Service unavailable - FOLIO system temporarily unavailable', *, request: Request, response: Response)

Bases: FolioServerError

Raised for 503 service unavailable errors. FOLIO system temporarily unavailable, possibly under maintenance or overloaded.

__init__(message: str = 'Service unavailable - FOLIO system temporarily unavailable', *, request: Request, response: Response) → None

exception folioclient.exceptions.FolioGatewayTimeoutError(message: str = 'Gateway timeout - FOLIO API gateway response timeout', *, request: Request, response: Response)

Bases: FolioServerError

Raised for 504 gateway timeout errors. API gateway timeout waiting for response from FOLIO module.

__init__(message: str = 'Gateway timeout - FOLIO API gateway response timeout', *, request: Request, response: Response) → None

folioclient.exceptions.folio_errors(func: Callable[[P], T]) → Callable[[P], T]

folioclient.exceptions.folio_errors(func: Callable[[P], Awaitable[T]]) → Callable[[P], Awaitable[T]]

Decorator that converts httpx exceptions to FOLIO-specific exceptions.

This decorator catches both httpx.RequestError (connection issues) and httpx.HTTPStatusError (HTTP status errors) and re-raises them as more specific FOLIO exceptions with meaningful names in the FOLIO context.

Works with both synchronous and asynchronous functions.

Usage:

>>> @folio_errors
... def get_user(self, user_id: str):
...     response = self._client.get(f"/users/{user_id}")
...     response.raise_for_status()
...     return response.json()

>>> @folio_errors
... async def get_user_async(self, user_id: str):
...     response = await self._async_client.get(f"/users/{user_id}")
...     response.raise_for_status()
...     return response.json()

Usage Examples

Basic Exception Handling

from folioclient import FolioClient
from folioclient.exceptions import FolioClientClosed, FolioClientException
import httpx

client = FolioClient(...)

try:
    users = client.folio_get("/users", "users")
except httpx.HTTPStatusError as e:
    print(f"HTTP error: {e.response.status_code}")
except FolioClientClosed:
    print("Client has been closed")
except FolioClientException as e:
    print(f"FolioClient error: {e}")

Async Exception Handling

import asyncio
from folioclient import FolioClient
from folioclient.exceptions import FolioClientClosed

async def handle_errors():
    client = FolioClient(...)
    
    try:
        users = await client.folio_get_async("/users", "users")
    except FolioClientClosed:
        print("Client was closed during operation")
    except Exception as e:
        print(f"Unexpected error: {e}")
    finally:
        await client.close()

asyncio.run(handle_errors())