Exceptions

All exceptions are importable from the top-level almaapitk package. Catch the base AlmaAPIError to handle any API failure, or a specific subclass for targeted handling. AlmaValidationError (and its subclass CredentialError) derive from ValueError.

AlmaAPIError

AlmaAPIError(
    message: str,
    status_code: int = None,
    response=None,
    tracking_id: Optional[str] = None,
    alma_code: str = "",
)

Bases: Exception

General Alma API error.

Carries the HTTP status, the underlying requests.Response, and -- when the failing response body included an Alma errorList payload -- the per-error trackingId and errorCode Ex Libris support uses to investigate cases (issue #10). Both fields default to safe sentinels (None / "") so call sites that construct exceptions without a parsed body (tests, the typed-subclass constructors, the legacy (message, status_code, response) positional path used pre-#10) keep working unchanged.

Attributes:

Name	Type	Description
status_code		HTTP status code of the failing response, or None for synthetic errors raised outside the response handler.
response		The underlying requests.Response (or test double).
tracking_id		The trackingId field from errorList.error[0]. None when the body had no errorList or no trackingId entry.
alma_code		The errorCode field from errorList.error[0], normalised to str. Empty string when no code was present -- chosen over None so log formatters can interpolate it without a falsy guard.

Source code in src/almaapitk/client/AlmaAPIClient.py

def __init__(
    self,
    message: str,
    status_code: int = None,
    response=None,
    tracking_id: Optional[str] = None,
    alma_code: str = "",
):
    super().__init__(message)
    self.status_code = status_code
    self.response = response
    self.tracking_id = tracking_id
    self.alma_code = alma_code

AlmaValidationError

Bases: ValueError

Validation error for Alma API requests.

AlmaAuthenticationError

AlmaAuthenticationError(
    message: str,
    status_code: int = None,
    response=None,
    tracking_id: Optional[str] = None,
    alma_code: str = "",
)

Bases: AlmaAPIError

API authentication failed (HTTP 401).

Source code in src/almaapitk/client/AlmaAPIClient.py

def __init__(
    self,
    message: str,
    status_code: int = None,
    response=None,
    tracking_id: Optional[str] = None,
    alma_code: str = "",
):
    super().__init__(message)
    self.status_code = status_code
    self.response = response
    self.tracking_id = tracking_id
    self.alma_code = alma_code

AlmaRateLimitError

AlmaRateLimitError(
    message: str,
    status_code: int = None,
    response=None,
    tracking_id: Optional[str] = None,
    alma_code: str = "",
)

Bases: AlmaAPIError

Alma API rate limit exceeded (HTTP 429).

Source code in src/almaapitk/client/AlmaAPIClient.py

def __init__(
    self,
    message: str,
    status_code: int = None,
    response=None,
    tracking_id: Optional[str] = None,
    alma_code: str = "",
):
    super().__init__(message)
    self.status_code = status_code
    self.response = response
    self.tracking_id = tracking_id
    self.alma_code = alma_code

AlmaServerError

AlmaServerError(
    message: str,
    status_code: int = None,
    response=None,
    tracking_id: Optional[str] = None,
    alma_code: str = "",
)

Bases: AlmaAPIError

Alma server-side error (HTTP 5xx).

Source code in src/almaapitk/client/AlmaAPIClient.py

def __init__(
    self,
    message: str,
    status_code: int = None,
    response=None,
    tracking_id: Optional[str] = None,
    alma_code: str = "",
):
    super().__init__(message)
    self.status_code = status_code
    self.response = response
    self.tracking_id = tracking_id
    self.alma_code = alma_code

AlmaResourceNotFoundError

AlmaResourceNotFoundError(
    message: str,
    status_code: int = None,
    response=None,
    tracking_id: Optional[str] = None,
    alma_code: str = "",
)

Bases: AlmaAPIError

Requested Alma resource was not found (HTTP 404).

Source code in src/almaapitk/client/AlmaAPIClient.py

def __init__(
    self,
    message: str,
    status_code: int = None,
    response=None,
    tracking_id: Optional[str] = None,
    alma_code: str = "",
):
    super().__init__(message)
    self.status_code = status_code
    self.response = response
    self.tracking_id = tracking_id
    self.alma_code = alma_code

AlmaDuplicateInvoiceError

AlmaDuplicateInvoiceError(
    message: str,
    status_code: int = None,
    response=None,
    tracking_id: Optional[str] = None,
    alma_code: str = "",
)

Bases: AlmaAPIError

Invoice already exists for the given vendor (Alma error code 402459).

Source code in src/almaapitk/client/AlmaAPIClient.py

def __init__(
    self,
    message: str,
    status_code: int = None,
    response=None,
    tracking_id: Optional[str] = None,
    alma_code: str = "",
):
    super().__init__(message)
    self.status_code = status_code
    self.response = response
    self.tracking_id = tracking_id
    self.alma_code = alma_code

AlmaInvalidPolModeError

AlmaInvalidPolModeError(
    message: str,
    status_code: int = None,
    response=None,
    tracking_id: Optional[str] = None,
    alma_code: str = "",
)

Bases: AlmaAPIError

POL is not in the right mode for the requested operation (Alma error code 40166411).

Source code in src/almaapitk/client/AlmaAPIClient.py

def __init__(
    self,
    message: str,
    status_code: int = None,
    response=None,
    tracking_id: Optional[str] = None,
    alma_code: str = "",
):
    super().__init__(message)
    self.status_code = status_code
    self.response = response
    self.tracking_id = tracking_id
    self.alma_code = alma_code

CredentialError

Bases: AlmaValidationError

No API key could be resolved for the client (issue #143).

Raised by AlmaAPIClient when neither an explicit api_key= argument nor the environment-variable fallback supplies a key.

Subclasses AlmaValidationError (and therefore ValueError) so that callers who caught the old bare ValueError on a missing key continue to work unchanged.