Skip to content

Exceptions

Every exception almapy raises descends from AlmapyError, so a single except AlmapyError catches anything originating in the library.

The hierarchy

The classes below are rendered in source order, each showing its immediate base, which makes the overall shape hard to see. In full:

Exception
└── AlmapyError                          catch-all for anything almapy raises
    ├── _AlmaError                       internal; carries Alma's code and message
    │   ├── APIServerError               5xx, already retried before you see it
    │   │   └── MalformedResponseError   2xx whose body was not the promised format
    │   └── APIClientError               4xx, your request – not retried
    │       ├── ThresholdError           429, rate limit exceeded
    │       ├── BarcodeNotFoundError
    │       ├── BibNotInCollectionError
    │       ├── CannotBeLoanedError
    │       ├── CannotRenewError
    │       ├── ExpiredCardError
    │       ├── IllegalBarcodeError
    │       ├── InvalidCodeError
    │       ├── InvalidFieldError
    │       ├── ItemAlreadyLoanedToUserError
    │       ├── LoanBlockedError
    │       ├── LoanLimitError
    │       ├── LoanNotFoundError
    │       ├── MMSIdNotFoundError
    │       ├── NoItemsCanFulfillRequestError
    │       ├── POUpdateFailedError
    │       ├── ParallelLoanError
    │       ├── ParallelRequestError
    │       ├── RequestFailedError
    │       ├── ScanItemRetrievalError
    │       ├── UserIsNotAPatronError
    │       ├── UserMissingFieldError
    │       └── UserNotFoundError
    └── ThrottleTimeoutError             also a TimeoutError; raised locally,
                                         without a request being sent

Two things the per-class listing does not make obvious:

_AlmaError appears as the base of most classes but has no entry below, being private. It exists to hold Alma's numeric code and message; catch APIClientError or APIServerError instead, which is the distinction that actually matters.

ThrottleTimeoutError sits outside that branch entirely. It is raised by almapy's own rate limiter before any request goes out, so it carries no Alma error code, and it subclasses TimeoutError as well – except TimeoutError catches it too.

See Errors for which of these to expect in practice and how Alma's numeric codes map onto them.

Reference

More specific exceptions for Alma API errors, used in response to (non-HTTP) error codes.

AlmapyError

Bases: Exception

Root exception for all exceptions raised by almapy.

Catch this to handle any error originating from the library.

APIClientError 

APIClientError(code: str, msg: str)

Bases: _AlmaError

Base exception for generic client-caused errors (HTTP 400s).

APIServerError 

APIServerError(code: str, msg: str)

Bases: _AlmaError

Base exception for generic server-related errors (HTTP 500s).

MalformedResponseError 

MalformedResponseError(code: str, msg: str)

Bases: APIServerError

A success status whose body was not in the format the endpoint promised.

Alma, or a gateway in front of it, answered 2xx with an HTML page, an empty body or the wrong content type – typically while it is struggling. code is the HTTP status; error is the content type and a short body excerpt.

Retried for idempotent verbs and counted as backpressure like any APIServerError. Not replayed for POST or PATCH: Alma may well have applied the write before the response was mangled.

ThresholdError 

ThresholdError(code: str, msg: str)

Bases: APIClientError

Raised when the API rate limit is exceeded.

BarcodeNotFoundError 

BarcodeNotFoundError(code: str, msg: str)

Bases: APIClientError

Raised when the specified barcode was not found on Alma.

Attributes:

Name Type Description
barcode str

The barcode that was not found.

MMSIdNotFoundError 

MMSIdNotFoundError(code: str, msg: str)

Bases: APIClientError

Raised when the specified MMS ID was not found on Alma.

Attributes:

Name Type Description
mms str

The MMS ID that was not found.

LoanLimitError 

LoanLimitError(code: str, msg: str)

Bases: APIClientError

Raised when an item could not be loaned due to a limit on number of simultaneous loans.

LoanBlockedError 

LoanBlockedError(code: str, msg: str)

Bases: APIClientError

Raised when an item could not be loaned due to a block on the user.

Attributes:

Name Type Description
type str

The block type.
description str

The block description.
note str

The block note.
scope str

The block scope.

InvalidFieldError 

InvalidFieldError(code: str, msg: str)

Bases: APIClientError

Raised when the user object contained invalid fields, often roles.

Attributes:

Name Type Description
field_name str

The name of the invalid field.
field_value str

The invalid value.

RequestFailedError 

RequestFailedError(code: str, msg: str)

Bases: APIClientError

Generic exception for when request creation failed.

ParallelLoanError 

ParallelLoanError(code: str, msg: str)

Bases: APIClientError

Raised when an item was unable to be loaned because they have a loan on another copy.

ParallelRequestError 

ParallelRequestError(code: str, msg: str)

Bases: APIClientError

Raised when an item could not be requested because they have a request on another copy.

UserMissingFieldError 

UserMissingFieldError(msg: str, user_id: str)

Bases: APIClientError

Some fields in the user object are mandatory and Alma throws an error if they are absent.

Attributes:

Name Type Description
user_id str

The primary ID of the user.

CannotRenewError 

CannotRenewError(msg: str, loan_id: str)

Bases: APIClientError

Unable to renew a loan for whatever reason.

Raised in place of the generic client error when Alma returns code 401822 – the item is requested by someone else, the renewal limit is reached, or a block applies. Alma's own reason is in error.

Attributes:

Name Type Description
loan_id

The loan that could not be renewed.

UserNotFoundError 

UserNotFoundError(code: str, msg: str)

Bases: APIClientError

No user with the provided identifier exists on Alma.

Attributes:

Name Type Description
user_id str

The primary ID of the user.

InvalidCodeError 

InvalidCodeError(msg: str)

Bases: APIClientError

For when an invalid code is specified when updating an item.

ScanItemRetrievalError 

ScanItemRetrievalError(code: str, msg: str)

Bases: APIClientError

Raised by scan in endpoint when the scan succeeds but item info is not returned [?].

NoItemsCanFulfillRequestError 

NoItemsCanFulfillRequestError(code: str, msg: str)

Bases: APIClientError

Raised when creating a request that no items can fulfill.

POUpdateFailedError 

POUpdateFailedError(code: str, msg: str)

Bases: APIClientError

Raised when a PO could not be updated for any reason.

LoanNotFoundError 

LoanNotFoundError(code: str, msg: str)

Bases: APIClientError

Raised when a loan could not be found.

ExpiredCardError 

ExpiredCardError(code: str, msg: str)

Bases: APIClientError

Raised when creating a loan for a card that has expired.

ItemAlreadyLoanedToUserError 

ItemAlreadyLoanedToUserError(code: str, msg: str)

Bases: APIClientError

Raised when trying to create a loan for an item that is already loaned to the user.

IllegalBarcodeError 

IllegalBarcodeError(code: str, msg: str)

Bases: APIClientError

Raised when trying to retrieve an item with an illegal barcode.

CannotBeLoanedError 

CannotBeLoanedError(code: str, msg: str)

Bases: APIClientError

Raised when an item cannot be loaned from the circulation desk.

UserIsNotAPatronError 

UserIsNotAPatronError(code: str, msg: str)

Bases: APIClientError

Raised when a user cannot borrow because they either don't have a patron role or it has expired.

BibNotInCollectionError 

BibNotInCollectionError(code: str, msg: str)

Bases: APIClientError

Raised when creating a representation on a bib that is in no collection.

Alma Digital requires the bibliographic record to belong to at least one collection before a representation can hang off it.

ThrottleTimeoutError

Bases: TimeoutError, AlmapyError

Raised when max_wait is exceeded waiting for adaptive throttle.