Exceptions

Circuit Breaker exceptions.

CLASS	DESCRIPTION
`CircuitBreakerConfigError`	Raised when `CircuitBreakerConfig` is built with an unsupported combination of
`CircuitBreakerError`	Base error class.
`CircuitBreakerOpenError`	Raised when the circuit is open and no `on_circuit_open` callback is registered.
`CircuitBreakerPersistenceError`	Raised by a persistence backend for an unrecoverable store error on a write path

CircuitBreakerConfigError ¶

CircuitBreakerConfigError(*args: str | Exception | None)

Bases: CircuitBreakerError

Raised when CircuitBreakerConfig is built with an unsupported combination of options (for example, both handled_exceptions and ignored_exceptions).

Source code in aws_lambda_powertools/utilities/circuit_breaker_alpha/exceptions.py

def __init__(self, *args: str | Exception | None):
    self.message = str(args[0]) if args else ""
    self.details = "".join(str(arg) for arg in args[1:]) if args[1:] else None

CircuitBreakerError ¶

CircuitBreakerError(*args: str | Exception | None)

Bases: Exception

Base error class.

Overrides message/details formatting so the printed exception stays readable. See https://github.com/aws-powertools/powertools-lambda-python/issues/1772

Source code in aws_lambda_powertools/utilities/circuit_breaker_alpha/exceptions.py

def __init__(self, *args: str | Exception | None):
    self.message = str(args[0]) if args else ""
    self.details = "".join(str(arg) for arg in args[1:]) if args[1:] else None

CircuitBreakerOpenError ¶

CircuitBreakerOpenError(*args: str | Exception | None, circuit: CircuitInfo | None = None)

Bases: CircuitBreakerError

Raised when the circuit is open and no on_circuit_open callback is registered.

The rejected request never reached the downstream. The circuit snapshot is attached so the caller can decide how to respond.

PARAMETER	DESCRIPTION
`*args`	Standard error message/details. TYPE: `str \| Exception \| None` DEFAULT: `()`
`circuit`	Snapshot of the circuit at rejection time. TYPE: `CircuitInfo \| None` DEFAULT: `None`

Example

Handling an open circuit when no callback is registered

try:
    charge(order)
except CircuitBreakerOpenError as exc:
    logger.warning("rejected by circuit %s", exc.circuit.name)
    return {"statusCode": 202}

Source code in aws_lambda_powertools/utilities/circuit_breaker_alpha/exceptions.py

def __init__(self, *args: str | Exception | None, circuit: CircuitInfo | None = None):
    self.circuit = circuit
    super().__init__(*args)

CircuitBreakerPersistenceError ¶

CircuitBreakerPersistenceError(*args: str | Exception | None)

Bases: CircuitBreakerError

Raised by a persistence backend for an unrecoverable store error on a write path (persisting a state transition), where there is no safe local fallback.

Reads never raise this: get_state fails open (treats the circuit as closed) and only logs, so a degraded store can never become the outage the breaker is meant to prevent. Custom backends may raise this from their write primitives.

Source code in aws_lambda_powertools/utilities/circuit_breaker_alpha/exceptions.py

def __init__(self, *args: str | Exception | None):
    self.message = str(args[0]) if args else ""
    self.details = "".join(str(arg) for arg in args[1:]) if args[1:] else None