exceptions

azure_bootstrap.exceptions ¶

Project-neutral exception hierarchy for pipelined applications.

Distinct from :mod:azure_bootstrap.models.exceptions (which carries the v1 RepositoryError family for config-source failures). This module's tree gives consumers an is_unrecoverable(exc) classifier so the Service Bus consumer wrapper can route failures to dead-letter vs abandon without hard-coding project-specific exception types.

Classes:

Name	Description
`PipelineError`	Base for any application-level pipeline failure.
`UnrecoverableError`	Marker: this failure will never succeed on retry.
`InvalidMessageError`	Queue payload failed schema validation.
`OversizedAttachmentError`	Attachment exceeded a configured byte cap.
`MalformedAttachmentError`	Magic-byte/MIME-type validation failed for the bytes received.
`ZipBombError`	Archive contains too many entries or excessive declared uncompressed size.
`UpstreamResourceMissing`	A resource expected to exist (blob, table row, secret) was 404.
`TransientError`	Marker for known-recoverable failures.
`RateLimitError`	HTTP 429 or equivalent — caller should back off.
`NetworkError`	Connection / timeout failure against an external service.
`AuthenticationError`	Token expired or RBAC denied.

Functions:

Name	Description
`is_unrecoverable`	The consumer's classifier — single `isinstance` check.
`register_unrecoverable`	Extend `DEFAULT_UNRECOVERABLE_TYPES` at runtime.

PipelineError ¶

Bases: Exception

Base for any application-level pipeline failure.

UnrecoverableError ¶

Bases: PipelineError

Marker: this failure will never succeed on retry.

Consumers MUST dead-letter messages whose handlers raised any subclass of UnrecoverableError. Anything else is transient (abandon → broker redelivers).

InvalidMessageError ¶

Bases: UnrecoverableError

Queue payload failed schema validation.

OversizedAttachmentError ¶

Bases: UnrecoverableError

Attachment exceeded a configured byte cap.

MalformedAttachmentError ¶

Bases: UnrecoverableError

Magic-byte/MIME-type validation failed for the bytes received.

ZipBombError ¶

Bases: OversizedAttachmentError

Archive contains too many entries or excessive declared uncompressed size.

UpstreamResourceMissing ¶

Bases: UnrecoverableError

A resource expected to exist (blob, table row, secret) was 404.

TransientError ¶

Bases: PipelineError

Marker for known-recoverable failures.

Not in UnrecoverableError's tree, so consumers automatically retry.

RateLimitError ¶

Bases: TransientError

HTTP 429 or equivalent — caller should back off.

NetworkError ¶

Bases: TransientError

Connection / timeout failure against an external service.

AuthenticationError ¶

Bases: TransientError

Token expired or RBAC denied.

Marked transient because the cause is often token-cache staleness — retry with fresh credentials usually succeeds. Apps with hard auth failures can subclass and re-parent under UnrecoverableError (or register the subclass via :func:register_unrecoverable).

is_unrecoverable ¶

is_unrecoverable(exc: BaseException) -> bool

The consumer's classifier — single isinstance check.

Source code in azure_bootstrap/exceptions/__init__.py

def is_unrecoverable(exc: BaseException) -> bool:
    """The consumer's classifier — single ``isinstance`` check."""
    return isinstance(exc, DEFAULT_UNRECOVERABLE_TYPES)

register_unrecoverable ¶

register_unrecoverable(*types: type[Exception]) -> None

Extend DEFAULT_UNRECOVERABLE_TYPES at runtime.

Useful when the "unrecoverable" type lives in a third-party SDK and can't be made to inherit from :class:UnrecoverableError directly.

Source code in azure_bootstrap/exceptions/__init__.py

def register_unrecoverable(*types: type[Exception]) -> None:
    """Extend ``DEFAULT_UNRECOVERABLE_TYPES`` at runtime.

    Useful when the "unrecoverable" type lives in a third-party SDK and can't
    be made to inherit from :class:`UnrecoverableError` directly.
    """
    global DEFAULT_UNRECOVERABLE_TYPES
    new = list(DEFAULT_UNRECOVERABLE_TYPES)
    for t in types:
        if isinstance(t, type) and issubclass(t, BaseException) and t not in new:
            new.append(t)
    DEFAULT_UNRECOVERABLE_TYPES = tuple(new)