Custom Exception Hierarchies

Domain exceptions group related failures so callers catch at the right granularity. A shallow tree under one package-specific base beats dozens of unrelated Exception subclasses.

Recipe

class AppError(Exception):
    """Base for all service errors."""
 
class ValidationError(AppError):
    def __init__(self, field: str, message: str) -> None:
        self.field = field
        super().__init__(f"{field}: {message}")

When to reach for this:

• HTTP/API layers map exception types to status codes
• Callers need to catch all payment errors but not all app errors
• Libraries export a stable public exception base
• Metrics/alerts label by exception class
• Tests assert specific failure types

Working Example

class BillingError(Exception):
    """Raised for billing subsystem failures."""
 
class CardDeclined(BillingError):
    def __init__(self, last4: str, reason: str) -> None:
        self.last4 = last4
        self.reason = reason
        super().__init__(f"card *{last4} declined: {reason}")
 
class InsufficientFunds(CardDeclined):
    pass
 
class InvoiceError(BillingError):
    pass
 
def charge(card_last4: str, amount: float) -> None:
    if amount > 1000:
        raise InsufficientFunds(card_last4, "insufficient funds")
    if amount < 0:
        raise InvoiceError("negative amount")
 
def handle_payment() -> str:
    try:
        charge("4242", 2000)
    except CardDeclined as exc:
        return f"retry with new card ({exc.reason})"
    except BillingError:
        return "billing unavailable"
    return "ok"
 
print(handle_payment())

What this demonstrates:

• Package base BillingError catches any billing failure
• CardDeclined adds fields for handlers and logs
• Subclasses specialize without duplicating handler logic
• Separate branches for recoverable vs generic billing errors

Deep Dive

How It Works

• Subclass Exception (not BaseException) for application errors
• One module-level or package-level base per bounded context
• Attach attributes on __init__ before super().__init__(message)
• Keep hierarchy shallow (base + 2-3 levels)
• Document which exceptions cross package boundaries

Hierarchy Guidelines

Gotchas

• Catch-all except Exception masking bugs - too broad handlers hide KeyboardInterrupt if mis-scoped. Fix: catch your base, then specific types.
• Deep inheritance trees - behavior duplicated across siblings. Fix: composition of fields, not subclass stacks.
• String-only errors - parsing message text in handlers. Fix: structured attributes (field, code).
• Leaking internal exceptions - DB driver errors reach API clients. Fix: wrap at boundary with from exc.
• Empty exception classes without docs - maintainers guess when to raise. Fix: docstring per class with raise conditions.

Alternatives

FAQs

Related

• Raising & Chaining - wrap with from
• Exception Groups & except* - concurrent errors
• Exceptions Basics - catch ordering
• Errors & Logging Best Practices - fail loudly

Stack versions: This page was written for Python 3.14.0 (stable 3.14, maintenance 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.