Exceptions

Custom exceptions for pykada.

All exceptions carry status_code, response_body, and endpoint attributes so callers can inspect what went wrong without parsing message strings.

All pykada exceptions inherit from VerkadaError so you can catch any API error with a single except VerkadaError clause, or handle specific cases precisely:

from pykada import (
    VerkadaAuthError,
    VerkadaNotFoundError,
    VerkadaRateLimitError,
    VerkadaServerError,
)

Every exception exposes:

• status_code — the HTTP status code (int | None)

• response_body — raw response text (str | None)

• endpoint — the URL that was called (str | None)

VerkadaRateLimitError additionally exposes:

• retry_after — seconds to wait before retrying, parsed from the Retry-After header (int | None)

Exception hierarchy

VerkadaError (base)
├── VerkadaAuthError       (401 Unauthorized)
├── VerkadaForbiddenError  (403 Forbidden)
├── VerkadaNotFoundError   (404 Not Found)
├── VerkadaRateLimitError  (429 Too Many Requests)
├── VerkadaServerError     (5xx Server Error)
└── VerkadaAPIError        (other HTTP errors)

class pykada.exceptions.VerkadaError(message, *, status_code=None, response_body=None, endpoint=None)

Bases: Exception

Base exception for all pykada errors.

Parameters:

• message (str)

• status_code (int | None)

• response_body (str | None)

• endpoint (str | None)

class pykada.exceptions.VerkadaAuthError(message, *, status_code=None, response_body=None, endpoint=None)

Bases: VerkadaError

Raised on 401 Unauthorized. Usually means the API key is missing, expired, or invalid.

Parameters:

• message (str)

• status_code (int | None)

• response_body (str | None)

• endpoint (str | None)

class pykada.exceptions.VerkadaForbiddenError(message, *, status_code=None, response_body=None, endpoint=None)

Bases: VerkadaError

Raised on 403 Forbidden. The API key is valid but lacks permission for this resource.

Parameters:

• message (str)

• status_code (int | None)

• response_body (str | None)

• endpoint (str | None)

class pykada.exceptions.VerkadaNotFoundError(message, *, status_code=None, response_body=None, endpoint=None)

Bases: VerkadaError

Raised on 404 Not Found. The requested resource (camera, user, door, etc.) does not exist.

Parameters:

• message (str)

• status_code (int | None)

• response_body (str | None)

• endpoint (str | None)

class pykada.exceptions.VerkadaRateLimitError(message, *, status_code=429, response_body=None, endpoint=None, retry_after=None)

Bases: VerkadaError

Raised on 429 Too Many Requests (after all retries are exhausted). Check retry_after for the number of seconds to wait before retrying.

Parameters:

• message (str)

• status_code (int | None)

• response_body (str | None)

• endpoint (str | None)

• retry_after (int | None)

class pykada.exceptions.VerkadaServerError(message, *, status_code=None, response_body=None, endpoint=None)

Bases: VerkadaError

Raised on 5xx responses or when all retries are exhausted on a server error.

Parameters:

• message (str)

• status_code (int | None)

• response_body (str | None)

• endpoint (str | None)

class pykada.exceptions.VerkadaAPIError(message, *, status_code=None, response_body=None, endpoint=None)

Bases: VerkadaError

Raised for any other HTTP error not covered by a more specific exception.

Parameters:

• message (str)

• status_code (int | None)

• response_body (str | None)

• endpoint (str | None)