Creating Custom Exceptions in Python0%

Modern Exception Handling: Exception Groups, except*, and add_note()

Creating Custom Exceptions in Python

Intermediate8 min read•Updated: 2026-10-01

Creating Custom Exceptions in Python

While Python's standard library provides dozens of built-in exceptions, production systems frequently encounter domain-specific error conditions that standard exceptions like ValueError or RuntimeError cannot clearly describe. By creating Custom Exceptions, you provide descriptive, domain-aligned error types that make debugging, automated recovery, and API design vastly more intuitive.

1. Defining a Basic Custom Exception

A custom exception is simply a class that inherits from the built-in Exception class (or one of its subclasses):

1class InsufficientFundsError(Exception):
2    """Raised when an account balance is insufficient for a withdrawal."""
3    pass
4 
5def process_withdrawal(balance: float, amount: float):
6    if amount > balance:
7        raise InsufficientFundsError(
8            f"Cannot withdraw ₹{amount:,.2f}. Current balance is only ₹{balance:,.2f}."
9        )
10    return balance - amount
11 
12try:
13    process_withdrawal(500, 1200)
14except InsufficientFundsError as err:
15    print(f"Transaction Aborted: {err}")

Naming Convention: Always end custom exception class names with Error (e.g., ValidationError, DatabaseTimeoutError) in accordance with PEP 8.

2. Designing Exception Hierarchies

In enterprise applications, libraries, and frameworks, best practice dictates defining a common application base exception. All other custom exceptions in that module inherit from this base. This allows callers to catch the top-level parent to intercept any error from the module, or catch individual children for targeted handling.

1ECommerceError (Base)
├── UserAuthenticationError
├── CartValidationError
│    ├── OutOfStockError
│    └── MaxQuantityExceededError
└── PaymentProcessingError

Implementing the Hierarchy

1class ECommerceError(Exception):
2    """Base exception for all errors in the e-commerce domain."""
3    pass
4 
5class CartValidationError(ECommerceError):
6    """Raised when cart items violate purchasing rules."""
7    pass
8 
9class OutOfStockError(CartValidationError):
10    """Raised when an inventory count cannot satisfy demand."""
11    pass
12 
13class PaymentProcessingError(ECommerceError):
14    """Raised when billing gateway fails."""
15    pass

Catching at Different Levels

1try:
2    # Business logic here
3    raise OutOfStockError("Item SKU-981 is sold out.")
4except CartValidationError as err:
5    # Catches OutOfStockError AND MaxQuantityExceededError
6    print(f"Cart issue: {err}")
7except ECommerceError as err:
8    # Catches ANY other e-commerce error
9    print(f"General store issue: {err}")

3. Adding Rich Metadata and Custom Attributes

Custom exceptions can store structured attributes—such as HTTP status codes, item IDs, timestamps, or validation failure lists—enabling upstream handlers to programmatically inspect the error without parsing error message strings:

1class InventoryError(Exception):
  def __init__(self, sku: str, requested_qty: int, available_qty: int):
      self.sku = sku
      self.requested_qty = requested_qty
      self.available_qty = available_qty
      self.deficit = requested_qty - available_qty
      
      message = (
          f"SKU '{sku}': Requested {requested_qty} units, "
          f"but only {available_qty} are in stock (Shortfall: {self.deficit})."
      )
      super().__init__(message)
13 
14def reserve_stock(sku: str, qty: int):
  stock_levels = {"SKU-A": 10, "SKU-B": 2}
  available = stock_levels.get(sku, 0)
  
  if qty > available:
      raise InventoryError(sku, qty, available)
  
  print(f"Reserved {qty} units of {sku}.")
22 
23try:
  reserve_stock("SKU-B", 5)
25except InventoryError as err:
  # Programmatic recovery using structured attributes
  print(f"Log: Stock shortage for item {err.sku}")
  print(f"Suggest ordering remaining {err.deficit} units from supplier.")

4. Best Practices Summary

1
Subclass Exception, not BaseException: Inheriting from BaseException bypasses standard except Exception: handlers and interrupts system signals.
2
Document with Docstrings: Document what scenario triggers the custom exception.
3
Keep them Lightweight: Only add custom attributes when callers will realistically need them for recovery or auditing.
4
Preserve super().__init__(): Always pass the formatted string message to the parent constructor so str(err) and tracebacks display the message cleanly.

⚠️ Common Intermediate Mistakes & Gotchas

1. Not Inheriting from `Exception`

Always inherit custom exceptions from Exception (or an application-level base exception), never directly from BaseException.

2. Over-Complicating Custom Exceptions

Keep custom exceptions lightweight. They exist to categorize domain failures cleanly, so a descriptive name and message are usually all you need.

💻 Try It Yourself: Custom Authentication Exception Hierarchy

Scenario

Create an AuthError base exception, with subclasses UserNotFoundError and InvalidCredentialsError. Write a simple login verification function demonstrating both.

Complete Solution

1class AuthError(Exception):
2    """Base exception for authentication failures."""
3    pass
4 
5class UserNotFoundError(AuthError):
6    pass
7 
8class InvalidPasswordError(AuthError):
9    pass
10 
11USERS_DB = {"aarav": "securepass123"}
12 
13def authenticate(username, password):
14    if username not in USERS_DB:
15        raise UserNotFoundError(f"User '{username}' does not exist.")
16    if USERS_DB[username] != password:
17        raise InvalidPasswordError("Incorrect password provided.")
18    return f"Welcome back, {username}!"
19 
20for u, p in [("aarav", "securepass123"), ("priya", "pass"), ("aarav", "wrong")]:
21    try:
22        print(authenticate(u, p))
23    except AuthError as err:
24        print(f"[{err.__class__.__name__}] {err}")

Expected Output

1Welcome back, aarav!
2[UserNotFoundError] User 'priya' does not exist.
3[InvalidPasswordError] Incorrect password provided.

Interactive Quiz• Knowledge Check

Practice Quiz

Question 1

Which class should your custom exception inherit from directly or indirectly in modern Python?

Question 2

What is the PEP 8 recommended naming convention for custom exception classes?

Question 3

What is the primary benefit of creating an application-level base exception (e.g. AppError(Exception))?

Question 4

How can callers access custom metadata (e.g. err.status_code) stored on an exception instance?

Question 5

Why should custom exceptions pass a message to super().__init__(message)?

🚀 What's Next?

In the next lesson, we will continue your intermediate Python journey with Project: Error-Handled Calculator (6: Exception Handling).

👉 Continue to Next Lesson: Project: Error-Handled Calculator →

Next Lesson

Modern Exception Handling: Exception Groups, except*, and add_note()

Continue learning with hands-on practice, examples, and exercises in the upcoming topic.

Related Lessons

Previous Lesson	Next Lesson
Raising Exceptions	Modern Exception Handling: Exception Groups, except*, and add_note()

Practice Quiz

Test your understanding of this lesson with 5 questions. Each question has one correct answer.

Previous Next

PreviousPrevNext

MSK Institute • Shikohabad

Loading Page Content...

Preparing courses, live labs, and learning resources.सामग्री लोड हो रही है, कृपया प्रतीक्षा करें...

Connecting serverPlease wait...

💻 Practical Labs🚀 Free Demo📜 Verified Certificates

Modern Exception Handling: Exception Groups, except*, and add_note()

Creating Custom Exceptions in Python

Intermediate8 min read•Updated: 2026-10-01

Study Materials Cheatsheet

Creating Custom Exceptions in Python

1. Defining a Basic Custom Exception

A custom exception is simply a class that inherits from the built-in Exception class (or one of its subclasses):

1class InsufficientFundsError(Exception):
2    """Raised when an account balance is insufficient for a withdrawal."""
3    pass
4 
5def process_withdrawal(balance: float, amount: float):
6    if amount > balance:
7        raise InsufficientFundsError(
8            f"Cannot withdraw ₹{amount:,.2f}. Current balance is only ₹{balance:,.2f}."
9        )
10    return balance - amount
11 
12try:
13    process_withdrawal(500, 1200)
14except InsufficientFundsError as err:
15    print(f"Transaction Aborted: {err}")

Naming Convention: Always end custom exception class names with Error (e.g., ValidationError, DatabaseTimeoutError) in accordance with PEP 8.

2. Designing Exception Hierarchies

1ECommerceError (Base)
├── UserAuthenticationError
├── CartValidationError
│    ├── OutOfStockError
│    └── MaxQuantityExceededError
└── PaymentProcessingError

Implementing the Hierarchy

1class ECommerceError(Exception):
2    """Base exception for all errors in the e-commerce domain."""
3    pass
4 
5class CartValidationError(ECommerceError):
6    """Raised when cart items violate purchasing rules."""
7    pass
8 
9class OutOfStockError(CartValidationError):
10    """Raised when an inventory count cannot satisfy demand."""
11    pass
12 
13class PaymentProcessingError(ECommerceError):
14    """Raised when billing gateway fails."""
15    pass

Catching at Different Levels

1try:
2    # Business logic here
3    raise OutOfStockError("Item SKU-981 is sold out.")
4except CartValidationError as err:
5    # Catches OutOfStockError AND MaxQuantityExceededError
6    print(f"Cart issue: {err}")
7except ECommerceError as err:
8    # Catches ANY other e-commerce error
9    print(f"General store issue: {err}")

3. Adding Rich Metadata and Custom Attributes

1class InventoryError(Exception):
  def __init__(self, sku: str, requested_qty: int, available_qty: int):
      self.sku = sku
      self.requested_qty = requested_qty
      self.available_qty = available_qty
      self.deficit = requested_qty - available_qty
      
      message = (
          f"SKU '{sku}': Requested {requested_qty} units, "
          f"but only {available_qty} are in stock (Shortfall: {self.deficit})."
      )
      super().__init__(message)
13 
14def reserve_stock(sku: str, qty: int):
  stock_levels = {"SKU-A": 10, "SKU-B": 2}
  available = stock_levels.get(sku, 0)
  
  if qty > available:
      raise InventoryError(sku, qty, available)
  
  print(f"Reserved {qty} units of {sku}.")
22 
23try:
  reserve_stock("SKU-B", 5)
25except InventoryError as err:
  # Programmatic recovery using structured attributes
  print(f"Log: Stock shortage for item {err.sku}")
  print(f"Suggest ordering remaining {err.deficit} units from supplier.")

4. Best Practices Summary

1
Subclass Exception, not BaseException: Inheriting from BaseException bypasses standard except Exception: handlers and interrupts system signals.
2
Document with Docstrings: Document what scenario triggers the custom exception.
3
Keep them Lightweight: Only add custom attributes when callers will realistically need them for recovery or auditing.
4
Preserve super().__init__(): Always pass the formatted string message to the parent constructor so str(err) and tracebacks display the message cleanly.

⚠️ Common Intermediate Mistakes & Gotchas

1. Not Inheriting from `Exception`

Always inherit custom exceptions from Exception (or an application-level base exception), never directly from BaseException.

2. Over-Complicating Custom Exceptions

Keep custom exceptions lightweight. They exist to categorize domain failures cleanly, so a descriptive name and message are usually all you need.

💻 Try It Yourself: Custom Authentication Exception Hierarchy

Scenario

Create an AuthError base exception, with subclasses UserNotFoundError and InvalidCredentialsError. Write a simple login verification function demonstrating both.

Complete Solution

1class AuthError(Exception):
2    """Base exception for authentication failures."""
3    pass
4 
5class UserNotFoundError(AuthError):
6    pass
7 
8class InvalidPasswordError(AuthError):
9    pass
10 
11USERS_DB = {"aarav": "securepass123"}
12 
13def authenticate(username, password):
14    if username not in USERS_DB:
15        raise UserNotFoundError(f"User '{username}' does not exist.")
16    if USERS_DB[username] != password:
17        raise InvalidPasswordError("Incorrect password provided.")
18    return f"Welcome back, {username}!"
19 
20for u, p in [("aarav", "securepass123"), ("priya", "pass"), ("aarav", "wrong")]:
21    try:
22        print(authenticate(u, p))
23    except AuthError as err:
24        print(f"[{err.__class__.__name__}] {err}")

Expected Output

1Welcome back, aarav!
2[UserNotFoundError] User 'priya' does not exist.
3[InvalidPasswordError] Incorrect password provided.

Interactive Quiz• Knowledge Check

Practice Quiz

Question 1

Which class should your custom exception inherit from directly or indirectly in modern Python?

Question 2

What is the PEP 8 recommended naming convention for custom exception classes?

Question 3

What is the primary benefit of creating an application-level base exception (e.g. AppError(Exception))?

Question 4

How can callers access custom metadata (e.g. err.status_code) stored on an exception instance?

Question 5

Why should custom exceptions pass a message to super().__init__(message)?

🚀 What's Next?

In the next lesson, we will continue your intermediate Python journey with Project: Error-Handled Calculator (6: Exception Handling).

👉 Continue to Next Lesson: Project: Error-Handled Calculator →

Next Lesson

Modern Exception Handling: Exception Groups, except*, and add_note()

Continue learning with hands-on practice, examples, and exercises in the upcoming topic.

Related Lessons

Previous Lesson	Next Lesson
Raising Exceptions	Modern Exception Handling: Exception Groups, except*, and add_note()

Practice Quiz

Test your understanding of this lesson with 5 questions. Each question has one correct answer.

Previous Next

Creating Custom Exceptions in Python

1. Defining a Basic Custom Exception

2. Designing Exception Hierarchies

Implementing the Hierarchy

Catching at Different Levels

3. Adding Rich Metadata and Custom Attributes

4. Best Practices Summary

⚠️ Common Intermediate Mistakes & Gotchas

1. Not Inheriting from Exception

2. Over-Complicating Custom Exceptions

💻 Try It Yourself: Custom Authentication Exception Hierarchy

Scenario

Complete Solution

Expected Output

Practice Quiz

🚀 What's Next?

Modern Exception Handling: Exception Groups, except*, and add_note()

Related Lessons

Practice Quiz

Loading Page Content...

Creating Custom Exceptions in Python

1. Defining a Basic Custom Exception

2. Designing Exception Hierarchies

Implementing the Hierarchy

Catching at Different Levels

3. Adding Rich Metadata and Custom Attributes

4. Best Practices Summary

⚠️ Common Intermediate Mistakes & Gotchas

1. Not Inheriting from Exception

2. Over-Complicating Custom Exceptions

💻 Try It Yourself: Custom Authentication Exception Hierarchy

Scenario

Complete Solution

Expected Output

Practice Quiz

🚀 What's Next?

Modern Exception Handling: Exception Groups, except*, and add_note()

Related Lessons

Practice Quiz

1. Not Inheriting from `Exception`

1. Not Inheriting from `Exception`