Custom Exceptions in Python — Why Your Tracebacks Vanish

Every production Python codebase eventually hits the same wall: generic exceptions stop being helpful. You catch a ValueError deep in a payment processing flow, and you have no idea if it came from a bad card number, an expired date, or a negative charge amount. You start writing long if/else chains in your except blocks just to figure out what actually broke. That's a design smell, and custom exceptions are the cure.

Python's exception hierarchy is a class hierarchy — exceptions are just classes that inherit from BaseException. That single insight unlocks everything. You can create your own exception types that carry extra context, sit in a logical hierarchy, and communicate intent at a glance. When a DatabaseConnectionError bubbles up through your stack, no one needs to read five lines of error message to understand what happened.

By the end of this article you'll know how to define clean custom exception classes, build a domain-specific exception hierarchy for a real project, attach useful context to your exceptions, and avoid the three mistakes that trip up almost everyone the first time they try this. You'll also know exactly how to answer the custom exception questions that come up in Python interviews.

Why Your Custom Exceptions Vanish in Python

A custom exception in Python is a user-defined class that inherits from Exception (or one of its subclasses). The core mechanic is simple: you subclass Exception, optionally add attributes, and raise instances of your class. This gives you control over the exception type, message, and payload — but only if you understand how Python's exception hierarchy and traceback machinery actually work.

In practice, the critical property is that custom exceptions are just regular classes. They can carry arbitrary data (e.g., an error code, a failed record ID), and they participate in the MRO (method resolution order). A common mistake is inheriting from BaseException instead of Exception — that makes your exception catchable by bare except: but also by KeyboardInterrupt handlers, which is almost never what you want. Another pitfall: forgetting to call super().__init__() can silently drop your message from the traceback.

Use custom exceptions when you need to distinguish error types in a try/except block — for example, a ValidationError vs. a DatabaseTimeoutError. They matter in real systems because they let you attach structured context (like a user ID or a request ID) directly to the exception, so your error handling and logging can act on it without parsing strings. Without them, you're stuck with generic Exception and string matching — fragile and opaque.

Why Inheriting From Exception (Not BaseException) Is the Right Starting Point

Python's exception tree has two main branches rooted at BaseException. System-level signals like KeyboardInterrupt and SystemExit live on one branch — these are things the runtime needs to handle, not your application. The Exception class is the root of everything your application code should throw and catch.

When you define a custom exception, you almost always inherit from Exception or one of its subclasses. Inheriting from BaseException directly means your exception would survive a bare except clause that's meant to catch only application errors, and it could accidentally suppress keyboard interrupts. That's a nasty, hard-to-debug bug.

Inheriting from a more specific built-in — like ValueError or TypeError — is even better when the semantics fit. If your custom error truly represents 'the value was wrong', subclass ValueError. That way, callers who catch ValueError will automatically catch yours too, which is the correct behaviour in most library code. But for domain errors that don't map to a built-in concept (think InsufficientFundsError or UserNotAuthorisedError), a direct Exception subclass is the cleaner choice.

The rule of thumb: be as specific as possible in the hierarchy, and prefer Exception over BaseException unless you have a very deliberate reason.

# ── exception_hierarchy_basics.py ──────────────────────────────────────────
# Demonstrates: correct base classes and why it matters at catch-time

# ❌ Inheriting from BaseException — almost never do this for app errors
class BadBaseException(BaseException):
    pass

# ✅ Inheriting from Exception — the right default for application errors
class AppError(Exception):
    """Base class for all errors raised by this application."""
    pass

# ✅ Inheriting from a built-in subclass when semantics match
class NegativeAmountError(ValueError):
    """Raised when a monetary amount is negative where only positive is valid."""
    pass


def process_payment(amount: float) -> str:
    if amount < 0:
        # We raise NegativeAmountError, but the except block below catches ValueError
        raise NegativeAmountError(f"Payment amount cannot be negative. Got: {amount}")
    return f"Payment of £{amount:.2f} processed successfully."


# --- Scenario 1: catching the specific type ---
try:
    process_payment(-50.0)
except NegativeAmountError as error:
    print(f"[Specific catch] {error}")

# --- Scenario 2: catching the PARENT type (ValueError) still works ---
# This is why subclassing ValueError is useful in library code:
# callers don't need to know about YOUR custom type to handle it sensibly.
try:
    process_payment(-50.0)
except ValueError as error:
    print(f"[Parent catch]   {error}")

# --- Scenario 3: proving BadBaseException escapes a normal except block ---
try:
    raise BadBaseException("I escape normal except clauses!")
except Exception:
    # BaseException subclasses are NOT caught here
    print("This line will NOT print.")
except BadBaseException as error:
    print(f"[BaseException catch] Had to catch it explicitly: {error}")

Adding Context to Custom Exceptions So They Actually Tell You Something

A custom exception class with no attributes is better than a generic one, but it still forces you to pack all your context into a string message. That means the calling code has to parse a string to understand what went wrong — and string parsing is fragile.

The better pattern is to treat your exception like a small data class. Override __init__ to accept structured fields, store them as attributes, and build the human-readable message from them. Now the code that catches the exception can branch on exception.status_code or exception.user_id without touching a string.

This also pays dividends in logging. When your exception carries structured data, your logger can record machine-readable fields alongside the message. That makes it searchable in tools like Datadog or Splunk — you can query for all InsufficientFundsError events where amount_requested > 10000 rather than running regex over log lines.

Don't forget __str__ and optionally __repr__. Python calls __str__ when the exception is printed or logged as a string. If you've overridden __init__ and don't set args correctly, the default string representation will be empty, which makes debugging a nightmare. The safest approach: always call super().__init__(message) with your constructed message string.

# ── context_rich_exceptions.py ─────────────────────────────────────────────
# Demonstrates: exceptions as data carriers, not just message strings

from datetime import datetime


class InsufficientFundsError(Exception):
    """
    Raised when a withdrawal or payment exceeds the available account balance.

    Attributes:
        account_id      -- the account that triggered the error
        amount_requested -- the amount the caller tried to move
        available_balance -- what was actually in the account
        timestamp        -- when this error occurred (useful for audit logs)
    """

    def __init__(
        self,
        account_id: str,
        amount_requested: float,
        available_balance: float,
    ) -> None:
        self.account_id = account_id
        self.amount_requested = amount_requested
        self.available_balance = available_balance
        self.shortfall = amount_requested - available_balance
        self.timestamp = datetime.utcnow()

        # Build the human-readable message ONCE and pass it to the parent.
        # This ensures str(exception) and repr(exception) both work correctly.
        message = (
            f"Account '{account_id}' has insufficient funds. "
            f"Requested: £{amount_requested:.2f}, "
            f"Available: £{available_balance:.2f}, "
            f"Shortfall: £{self.shortfall:.2f}"
        )
        super().__init__(message)   # ← critical: always call super().__init__


def withdraw(account_id: str, amount: float, balance: float) -> float:
    """Simulate a withdrawal. Returns new balance on success."""
    if amount > balance:
        raise InsufficientFundsError(
            account_id=account_id,
            amount_requested=amount,
            available_balance=balance,
        )
    return balance - amount


# --- Happy path ---
new_balance = withdraw(account_id="ACC-001", amount=200.0, balance=500.0)
print(f"Withdrawal successful. New balance: £{new_balance:.2f}")

# --- Error path: catching and inspecting structured attributes ---
try:
    withdraw(account_id="ACC-002", amount=1500.0, balance=300.0)
except InsufficientFundsError as error:
    # We can branch on the data, not on parsing a string
    print(f"\nCaught: {error}")                          # uses __str__ via super().__init__
    print(f"Account  : {error.account_id}")
    print(f"Requested: £{error.amount_requested:.2f}")
    print(f"Available: £{error.available_balance:.2f}")
    print(f"Shortfall: £{error.shortfall:.2f}")
    print(f"At       : {error.timestamp.strftime('%Y-%m-%d %H:%M:%S')} UTC")

    # Real-world: trigger a different UX flow depending on shortfall size
    if error.shortfall < 50:
        print("Suggestion: You're just short — consider a small top-up.")
    else:
        print("Suggestion: Please review your account balance before retrying.")

Building a Domain Exception Hierarchy for a Real Project

In a real codebase you don't just have one custom exception — you have a family of them. The smartest architecture defines a single base exception for your entire application or module, then branches from there. This gives callers maximum flexibility: they can catch everything from your module with one except clause, or pinpoint a specific error type when they need to.

Think about an e-commerce backend. At the top you might have ECommerceError. Below that: PaymentError, InventoryError, AuthenticationError. Below PaymentError: CardDeclinedError, InsufficientFundsError, FraudDetectedError. This mirrors how you'd talk about the domain in a meeting, which means new developers understand the code structure immediately.

Another huge win: middleware and framework error handlers can catch your top-level base exception and render a consistent error response, without knowing anything about the specific subclasses. A FastAPI exception handler that catches ECommerceError can return a structured JSON error to the client, while individual route functions handle the specific subtypes for business logic.

Keep your exception hierarchy in a dedicated exceptions.py file at the module root. Import from there everywhere. This single-source approach prevents circular imports and makes the hierarchy easy to document.

# ── domain_exception_hierarchy.py ──────────────────────────────────────────
# Demonstrates: a real-world exception hierarchy for an e-commerce module
# In a real project this lives in  src/ecommerce/exceptions.py

# ── LAYER 1: Application root ───────────────────────────────────────────────
class ECommerceError(Exception):
    """Root exception for the entire e-commerce module.
    Catch this in middleware/framework handlers to guarantee a
    structured error response for ANY problem from this domain.
    """
    pass


# ── LAYER 2: Domain groupings ────────────────────────────────────────────────
class PaymentError(ECommerceError):
    """All payment-related failures."""
    pass

class InventoryError(ECommerceError):
    """All stock/inventory-related failures."""
    pass

class AuthorisationError(ECommerceError):
    """All permission/authentication failures."""
    pass


# ── LAYER 3: Specific errors with rich context ───────────────────────────────
class CardDeclinedError(PaymentError):
    """Raised when a payment gateway declines a card."""

    def __init__(self, card_last_four: str, decline_code: str) -> None:
        self.card_last_four = card_last_four
        self.decline_code = decline_code
        super().__init__(
            f"Card ending {card_last_four} was declined (code: {decline_code})"
        )


class OutOfStockError(InventoryError):
    """Raised when a product cannot fulfil the requested quantity."""

    def __init__(self, product_sku: str, requested: int, available: int) -> None:
        self.product_sku = product_sku
        self.requested = requested
        self.available = available
        super().__init__(
            f"SKU '{product_sku}': requested {requested}, only {available} in stock."
        )


class InsufficientPermissionsError(AuthorisationError):
    """Raised when a user attempts an action they're not allowed to perform."""

    def __init__(self, user_id: str, required_role: str) -> None:
        self.user_id = user_id
        self.required_role = required_role
        super().__init__(
            f"User '{user_id}' lacks required role '{required_role}'."
        )


# ── Simulated service functions ───────────────────────────────────────────────
def charge_card(card_last_four: str, amount: float) -> None:
    """Simulate a payment gateway call."""
    # In real life: call Stripe/Braintree SDK here
    if card_last_four == "0000":   # simulate a declined card for demo
        raise CardDeclinedError(card_last_four=card_last_four, decline_code="insufficient_funds")

def reserve_stock(product_sku: str, quantity: int) -> None:
    """Simulate an inventory reservation."""
    stock_levels = {"WIDGET-42": 3, "GADGET-7": 100}
    available = stock_levels.get(product_sku, 0)
    if quantity > available:
        raise OutOfStockError(product_sku=product_sku, requested=quantity, available=available)

def admin_action(user_id: str) -> None:
    """Simulate an action that requires admin privileges."""
    non_admin_users = {"user-123", "user-456"}
    if user_id in non_admin_users:
        raise InsufficientPermissionsError(user_id=user_id, required_role="admin")


# ── Demonstrate catching at different levels of the hierarchy ─────────────────
test_cases = [
    lambda: charge_card("0000", 99.99),
    lambda: reserve_stock("WIDGET-42", 10),
    lambda: admin_action("user-123"),
]

for test in test_cases:
    try:
        test()
    except CardDeclinedError as error:
        # Specific handler: offer the user a chance to retry with another card
        print(f"[CardDeclined]   {error} — prompt user for alternative card")
    except InventoryError as error:
        # Catches OutOfStockError AND any future InventoryError subclasses
        print(f"[InventoryError] {error} — notify warehouse team")
    except ECommerceError as error:
        # Safety net: catches everything else from this module
        print(f"[ECommerceError] {error} — log and return 400 to client")

Exception Chaining: Using 'raise ... from' to Preserve the Full Story

Here's a scenario you'll hit constantly in production: you call a low-level library (database driver, HTTP client), it raises its own exception, and you want to wrap it in your domain exception — but you don't want to lose the original traceback. That original traceback is gold when you're debugging at 2am.

Python's raise ... from syntax is built for exactly this. When you write raise MyError('something went wrong') from original_exception, Python chains the two exceptions together. The full traceback shows both the root cause and the point where it was re-raised as your domain exception. Users of your library see your clean domain exception; you and your on-call engineer see the full story.

The alternative — catching and re-raising without from — loses the original exception context in Python 3 (though Python 3 does attach it implicitly in some cases via __context__). Being explicit with from is clearer and is considered the professional pattern.

If you deliberately want to suppress the original exception from the traceback (for security reasons, for example — you don't want a database error leaking internal table names to a client), use raise MyError('sanitised message') from None. That completely hides the original cause.

# ── exception_chaining.py ──────────────────────────────────────────────────
# Demonstrates: raise...from to preserve root cause during exception translation

import sqlite3


class DatabaseUnavailableError(Exception):
    """Raised when the application cannot reach or query the database."""

    def __init__(self, operation: str, original: Exception) -> None:
        self.operation = operation
        super().__init__(
            f"Database operation '{operation}' failed. See cause above for details."
        )


class UserRepository:
    """Thin data-access layer that translates low-level DB errors into domain errors."""

    def __init__(self, db_path: str) -> None:
        # Using an intentionally invalid path to simulate a connection failure
        self.db_path = db_path

    def find_user(self, user_id: int) -> dict:
        try:
            # sqlite3 will raise OperationalError if the DB doesn't exist/is locked
            connection = sqlite3.connect(self.db_path)
            cursor = connection.cursor()
            cursor.execute("SELECT id, name FROM users WHERE id = ?", (user_id,))
            row = cursor.fetchone()
            if row is None:
                return {}
            return {"id": row[0], "name": row[1]}

        except sqlite3.OperationalError as db_error:
            # Translate the low-level driver error into our domain exception.
            # The 'from db_error' chain preserves the original traceback.
            raise DatabaseUnavailableError(
                operation="find_user",
                original=db_error,
            ) from db_error   # ← this is the key line


# --- Example 1: raise...from shows BOTH tracebacks ---
repo = UserRepository(db_path="/nonexistent/path/app.db")

try:
    repo.find_user(user_id=42)
except DatabaseUnavailableError as error:
    print(f"Domain error caught: {error}")
    # In a real app you'd log the full traceback with logging.exception()
    # which automatically includes the chained cause
    print(f"Root cause type : {type(error.__cause__).__name__}")
    print(f"Root cause msg  : {error.__cause__}")

print()

# --- Example 2: raise...from None hides sensitive internals ---
class UserFetchError(Exception):
    """Sanitised error safe to return to an API client."""
    pass

try:
    try:
        # Simulate an internal error with sensitive details
        raise sqlite3.OperationalError("no such table: internal_user_pii")
    except sqlite3.OperationalError:
        # We don't want 'internal_user_pii' leaking to the client
        raise UserFetchError("Unable to retrieve user. Please try again.") from None
except UserFetchError as error:
    print(f"Safe client error : {error}")
    print(f"Hidden cause      : {error.__cause__}")   # None — original is suppressed

Testing Custom Exceptions: Assert on Attributes, Not Messages

After building a rich custom exception with structured data, you need to test that the right exception is raised with the right attributes. The obvious approach is to assert on the string message: assert str(error) == 'some message'. But that's brittle. The message is a presentation detail that may change with locale, formatting tweaks, or refactoring. When it changes, your tests break even though the semantics are identical.

The robust pattern is to use pytest.raises and inspect the exception object directly. Check its type with isinstance or type, and assert on its attributes. This tests the contract (what data is passed) rather than the presentation (how it's formatted). This way, you can change the message format without touching your tests.

Additionally, test that the exception is properly picklable if you use it in multiprocessing or distributed systems. Custom exceptions that override __init__ without setting the args tuple correctly can break pickling. To be safe, ensure your __init__ passes a tuple to super().__init__(*args) or a single message string (which Python wraps into args).

# ── test_custom_exceptions.py ─────────────────────────────────────────────
# Demonstrates: testing custom exceptions by asserting on attributes, not messages

import pytest
from context_rich_exceptions import InsufficientFundsError, withdraw


def test_insufficient_funds_attributes():
    """Test that InsufficientFundsError carries the correct structured data."""
    with pytest.raises(InsufficientFundsError) as exc_info:
        withdraw(account_id="ACC-001", amount=500.0, balance=200.0)

    error = exc_info.value
    assert error.account_id == "ACC-001"
    assert error.amount_requested == 500.0
    assert error.available_balance == 200.0
    assert error.shortfall == 300.0
    # Do NOT assert on error.message or str(error) — that's presentation


def test_insufficient_funds_type_is_specific():
    """Test that the raised exception is exactly InsufficientFundsError, not a parent."""
    with pytest.raises(InsufficientFundsError):
        withdraw(account_id="ACC-002", amount=100.0, balance=50.0)


def test_withdrawal_success_returns_balance():
    """Happy path: no exception raised, correct returned value."""
    new_balance = withdraw(account_id="ACC-003", amount=100.0, balance=500.0)
    assert new_balance == 400.0


def test_exception_picklable():
    """Ensure the exception can be serialized (useful for multiprocessing)."""
    import pickle
    try:
        raise InsufficientFundsError("ACC-004", 200.0, 150.0)
    except InsufficientFundsError as e:
        pickled = pickle.dumps(e)
        unpickled = pickle.loads(pickled)
        assert unpickled.account_id == "ACC-004"
        assert unpickled.shortfall == 50.0

Why Define Custom Exceptions? (Because Built-Ins Are Not a Taxonomy)

Built-in exceptions like ValueError or RuntimeError are generic. They tell you what went wrong — not where or why in your domain. When a payment fails, raising a plain Exception forces every handler to parse a string to decide the next action. That’s error handling by regex, and it’s brittle.

Custom exceptions let you encode business logic directly into the exception type. A PaymentDeclinedError carries different remediation steps than InsufficientFundsError or FraudDetectionError. Downstream handlers use isinstance() to branch behavior without touching a single error message. This turns error handling from a guessing game into a type switch.

You also get grep-ability. Search your codebase for class PaymentDeclinedError and you instantly find every place the payment flow can fail. Try that with a string "declined" buried in an exception message.

// io.thecodeforge — python tutorial

class PaymentError(Exception):
    """Base for all payment failures in the gateway."""

class PaymentDeclinedError(PaymentError):
    """Card issuer declined the transaction."""

class InsufficientFundsError(PaymentError):
    """Balance too low for the requested amount."""

class FraudDetectionError(PaymentError):
    """Payment flagged by the fraud engine."""

def process_payment(amount: float, account_id: str) -> bool:
    # Simulate gateway logic
    if amount > 10000.0:
        raise FraudDetectionError(amount, account_id)
    if amount > get_balance(account_id):
        raise InsufficientFundsError(amount, get_balance(account_id))
    if random_issuer_decline():
        raise PaymentDeclinedError(account_id)
    return True

try:
    process_payment(15000.0, "acct_8472")
except FraudDetectionError:
    trigger_manual_review(account_id)
except InsufficientFundsError:
    suggest_lower_amount()

Raising and Handling Custom Exceptions (Don’t Catch What You Can’t Handle)

Raising a custom exception is trivial: raise MyCustomError("message"). The real skill is knowing where to catch it. The golden rule: catch exceptions at the layer that has enough context to handle them — not earlier, not later.

If you catch a DatabaseConnectionError inside the repository layer, what can you do there? Retry? Log? Close and open a new pool? That logic belongs in the service layer or the orchestrator that understands retry windows and backoff policies. Catching too early forces a cascade of re-raises or, worse, swallowing.

When you do catch, be specific. Never write except Exception: unless you are logging and re-raising. A bare except masks every bug — import errors, type errors, and your custom exceptions all collapse into a single silent handler. Catch the exact exception type or its parent hierarchy so that unrelated failures bubble up to the top-level handler.

// io.thecodeforge — python tutorial

class InventoryError(Exception):
    """Base inventory failure."""

class OutOfStockError(InventoryError):
    """Item quantity is zero."""

class AllocationError(InventoryError):
    """Cannot reserve items due to conflict."""

def allocate_item(order_id: str, sku: str, qty: int) -> None:
    if qty > get_stock(sku):
        raise OutOfStockError(f"SKU {sku}: requested {qty}, available {get_stock(sku)}")
    # allocation logic...

def fulfill_order(order_id: str) -> bool:
    try:
        for item in get_order_items(order_id):
            allocate_item(order_id, item['sku'], item['qty'])
        return True
    except OutOfStockError as e:
        notify_customer_refund(order_id, str(e))
        return False
    except AllocationError as e:
        trigger_reconciliation(order_id, str(e))
        raise  # re-raise, orchestrator must decide order-level impact

8.7-8.8. Defining and Predefined Clean-up Actions: Guaranteeing Finality

When an exception is raised, resources like file handles or locks may be left dangling. Python provides two canonical ways to define clean-up actions that execute regardless of how a block is exited: the try...finally statement and the with statement context manager. finally blocks are guaranteed to run after the try block, even if an exception propagates upward. For predefined clean-up, Python’s with statement automatically calls the __exit__ method on context managers (like open(), Lock.acquire()) to release external state. This ensures that custom exceptions don't leave resources in an inconsistent state—a silent failure that corrupts data. When designing custom exceptions, pair them with clean-up patterns: wrap risky code in try...finally to close connections, or define your own context manager via __enter__ and __exit__ to encapsulate cleanup logic. This prevents resource leaks that would otherwise mask your exception's root cause. Always prefer with over explicit finally for built-in types.

// io.thecodeforge — python tutorial
// Guarantee cleanup with finally

class DatabaseError(Exception):
    pass

def fetch_data():
    conn = open_connection()
    try:
        return conn.query()
    except Exception as e:
        raise DatabaseError("Query failed") from e
    finally:
        conn.close()  # Always runs

// Predefined cleanup via context manager
with open("data.txt", "r") as f:
    content = f.read()  # File auto-closes

8.10. Enriching Exceptions with Notes: Attach Live Debug Info

Standard exception messages are static—they capture the state at the moment of the exception, but debugging often requires contextual data that accumulates as the error propagates. Python 3.11 introduced BaseException.add_note(), allowing you to append structured, human-readable notes to an exception object without altering its original traceback. This is invaluable for custom exceptions in large codebases: you can enrich a ValidationError with the exact field values that failed, or add processing steps that occurred before a PaymentFailedError. Notes appear in the traceback under "Exception notes:", so they remain visible during logging. The pattern is simple: catch a custom exception, call exc.add_note("context"), and re-raise it (or let it propagate). This keeps your exception hierarchy clean while supplying the forensic details needed for debugging. Do not use notes for sensitive data like passwords—they may appear in logs. Instead, use them for transaction IDs, field names, or partial payloads.

// io.thecodeforge — python tutorial
// Enrich exceptions with add_note()

class OrderError(Exception):
    pass

def process_order(order_id: int):
    try:
        validate_payment(order_id)
    except PaymentError as e:
        e.add_note(f"order_id={order_id}, pricing_version=2.1")
        raise OrderError("Order failed") from e

// Traceback shows: Exception notes: order_id=42, pricing_version=2.1

Exception Hierarchy Design for Libraries and Frameworks

When building libraries or frameworks, a well-designed exception hierarchy is crucial for usability and maintainability. Users of your library need to catch specific exceptions without relying on fragile string matching or catching broad Exception classes. The key is to create a base exception for your library and derive all custom exceptions from it. This allows users to catch all library-specific errors with a single except YourLibraryError clause while still being able to handle specific cases.

For example, consider a hypothetical configparser library:

```python class ConfigError(Exception): """Base exception for all config-related errors."""

class ParseError(ConfigError): """Raised when a config file cannot be parsed."""

class ValidationError(ConfigError): """Raised when a config value fails validation."""

class MissingKeyError(ConfigError): """Raised when a required key is missing.""" ```

Users can then catch ConfigError to handle any configuration issue, or catch specific subclasses for granular control. This pattern is used by popular libraries like requests (with RequestException) and sqlalchemy (with SQLAlchemyError).

A common mistake is to create a single LibraryError and use error codes or messages to distinguish cases. This forces users to parse strings, which is fragile and defeats the purpose of custom exceptions. Instead, leverage Python's class hierarchy to encode the error type directly.

class ConfigError(Exception):
    """Base exception for all config-related errors."""

class ParseError(ConfigError):
    """Raised when a config file cannot be parsed."""

class ValidationError(ConfigError):
    """Raised when a config value fails validation."""

class MissingKeyError(ConfigError):
    """Raised when a required key is missing."""

# Usage
try:
    raise MissingKeyError("The 'database' key is required")
except ConfigError as e:
    print(f"Configuration error: {e}")
except ParseError as e:
    print(f"Parse error: {e}")

Adding Extra Attributes to Custom Exceptions

Custom exceptions become significantly more useful when they carry additional context beyond a simple message. By adding attributes, you can store structured data that helps debugging and error handling. For instance, an exception for a failed API call might include the HTTP status code, the response body, and the URL.

Here's how to define a custom exception with extra attributes:

``python class APIError(Exception): def __init__(self, message, status_code, response_body): super().__init__(message) self.status_code = status_code self.response_body = response_body ``

When raising this exception, you provide the extra data:

``python raise APIError("Request failed", 404, {"error": "Not found"}) ``

Now, when catching the exception, you can access these attributes:

``python try: make_request() except APIError as e: print(f"Status: {e.status_code}, Body: {e.response_body}") ``

This approach is far superior to embedding structured data in the message string, which would require parsing. It also enables automated handling: for example, you could retry on 5xx errors but not on 4xx errors by checking e.status_code.

A common pitfall is to overload the exception with too many attributes, making it hard to use. Stick to a few key pieces of information that directly aid in resolution.

class APIError(Exception):
    """Raised when an API call fails.

    Attributes:
        status_code: HTTP status code returned.
        response_body: Parsed JSON response body.
    """
    def __init__(self, message, status_code, response_body):
        super().__init__(message)
        self.status_code = status_code
        self.response_body = response_body

# Usage
try:
    raise APIError("Request failed", 500, {"error": "Internal server error"})
except APIError as e:
    if e.status_code >= 500:
        print("Server error, will retry")
    else:
        print(f"Client error: {e.response_body}")

Best Practices: When to Create Custom Exceptions

Not every error condition warrants a custom exception. Overusing them can clutter your codebase and confuse users. Follow these guidelines to decide when to create a custom exception:

Create a custom exception when: 1. The error is specific to your domain and needs to be caught separately from other errors. 2. You need to attach extra attributes to the exception (e.g., error codes, context). 3. You want to provide a clear, descriptive name that aids debugging. 4. You are building a library or framework where users need to catch your errors selectively.

Don't create a custom exception when: 1. A built-in exception already conveys the meaning (e.g., ValueError for invalid arguments, TypeError for wrong types). 2. The error is rare and doesn't need special handling. 3. You only need to differentiate by message; use a built-in with a descriptive message instead. 4. You are tempted to create a hierarchy that mirrors your class hierarchy (e.g., one exception per class).

A common anti-pattern is to create a custom exception for every possible failure mode. Instead, group related errors under a single exception with an attribute to distinguish them. For example, a DatabaseError with an error_code attribute is better than ConnectionError, QueryError, TimeoutError if they are handled similarly.

Another best practice is to inherit from Exception (not BaseException) because BaseException includes SystemExit, KeyboardInterrupt, etc., which you typically don't want to catch accidentally.

Finally, document your exceptions clearly. In the docstring of the function that raises them, list the exceptions and when they occur. This helps users of your code understand what to expect.

# Good: Custom exception for domain-specific error with extra attributes
class PaymentError(Exception):
    def __init__(self, message, transaction_id):
        super().__init__(message)
        self.transaction_id = transaction_id

# Bad: Unnecessary custom exception for a standard error
class NegativeNumberError(Exception):
    pass

# Better: Use built-in ValueError with a descriptive message
raise ValueError("Input must be non-negative")

# Good: Group related errors under one exception
class DatabaseError(Exception):
    def __init__(self, message, error_code):
        super().__init__(message)
        self.error_code = error_code

# Instead of: ConnectionError, QueryError, TimeoutError