Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/danielfm/pybreaker/llms.txt

Use this file to discover all available pages before exploring further.

Not every exception your code raises signals that a downstream system is failing. Business logic exceptions — such as CustomerNotFound, ValidationError, or PermissionDenied — indicate application-level issues, not infrastructure problems. If these are counted as failures, the circuit can trip even when the underlying service is perfectly healthy, causing unnecessary outages. PyBreaker lets you declare a list of excluded exceptions. Any exception matching an exclusion is re-raised normally but is not counted against the failure threshold and will not trip the circuit breaker.

​
Excluding by Exception Type

Pass exception types via the exclude parameter at construction time, or register them after the fact using add_excluded_exception / add_excluded_exceptions. 
# At creation time
db_breaker = pybreaker.CircuitBreaker(
    fail_max=5,
    reset_timeout=60,
    exclude=[CustomerValidationError]
)

# Or add later
db_breaker.add_excluded_exception(CustomerValidationError)
db_breaker.add_excluded_exceptions(ValidationError, PermissionError)
Exclusions based on type use issubclass internally, so subclasses of excluded exception types are also excluded. Registering ValidationError will also exclude EmailValidationError(ValidationError), PhoneValidationError(ValidationError), and so on.

​
Excluding with a Callable Predicate

When the exception type alone isn’t granular enough, pass a callable instead. The callable receives the exception instance and should return True if the exception should be excluded (not counted as a failure). 
# Only exclude HTTP 4xx errors (client errors), not 5xx (server errors)
db_breaker = pybreaker.CircuitBreaker(
    fail_max=5,
    reset_timeout=60,
    exclude=[lambda e: isinstance(e, HTTPError) and e.status_code < 500]
)
This is useful when the same exception class covers both expected conditions (e.g., 404 Not Found) and genuine failures (e.g., 503 Service Unavailable) and you need to distinguish them by value.

​
Mixing Types and Callables

Types and callables can be freely combined in the same exclude list. PyBreaker evaluates each entry in order and excludes the exception if any entry matches. 
db_breaker = pybreaker.CircuitBreaker(
    fail_max=5,
    reset_timeout=60,
    exclude=[
        CustomerValidationError,           # Type exclusion
        NotFoundError,                     # Type exclusion
        lambda e: isinstance(e, HTTPError) and e.status_code < 500  # Callable
    ]
)

​
Checking and Removing Exclusions

Inspect the current exclusion list or remove a previously registered exclusion at any time. Use is_system_error() to test how the circuit breaker would classify a specific exception instance. 
# Inspect current exclusions
print(db_breaker.excluded_exceptions)  # tuple

# Remove an exclusion
db_breaker.remove_excluded_exception(CustomerValidationError)

# Check if an exception would be treated as a system error
db_breaker.is_system_error(CustomerValidationError())  # False (excluded)
db_breaker.is_system_error(ConnectionError())           # True
is_system_error() returns False for excluded exceptions (they won’t count as failures) and True for everything else (they will).
Always be deliberate about which exceptions represent genuine system failure. Excluding too many exception types can hide real problems and prevent the circuit breaker from opening when the downstream service is actually degraded. As a rule of thumb: exclude exceptions that originate from the caller’s input or application logic, and let exceptions originating from network I/O, timeouts, and infrastructure errors pass through to the failure counter.

Build docs developers (and LLMs) love

Get started for freeTalk to us