Distinguish your technical failures from business rules

TL;DR: Use separate exception hierarchies for business and technical errors.

Problems Addressed 😔

• Confused contracts
• Mixed responsibilities and error treatment
• Difficult handling
• Poor readability
• Misleading signals
• Exceptions for expected cases
• Nested Exceptions
• Mixed exception hierarchies
• Improper error responses
• Tangled architectural concerns
• Mixed alarms

Related Code Smells 💨

https://maximilianocontieri.com/code-smell-72-return-codes?embedable=true

https://maximilianocontieri.com/code-smell-73-exceptions-for-expected-cases?embedable=true

https://maximilianocontieri.com/code-smell-80-nested-trycatch?embedable=true

https://www.linkedin.com/pulse/code-smell-184-exception-arrow-maximiliano-contieri?embedable=true

https://www.linkedin.com/pulse/code-smell-132-exception-try-too-broad-maximiliano-contieri?embedable=true

Steps 👣

1. Identify business exceptions
2. Identify technical exceptions
3. Create two separate exception hierarchies
4. Update the code to throw the right one
5. Adjust handlers accordingly

Sample Code 💻

Before 🚨

public void Withdraw(int amount) {
  if (amount > Balance) {
    throw new Exception("Insufficient funds");
    // You might want to show this error to end users
  }
  if (connection == null) {
    throw new Exception("Database not available");
    // Internal error, log and notify operators. 
    // Fail with a more generic error
  }
  Balance -= amount;
}

After 👉

// 1. Identify business exceptions
public class BusinessException : Exception {}
public class InsufficientFunds : BusinessException {}

// 2. Identify technical exceptions
public class TechnicalException : Exception {}
public class DatabaseUnavailable : TechnicalException {}

public void Withdraw(int amount) {
  // 3. Use the correct hierarchy
  if (amount > Balance) {
    throw new InsufficientFunds();
  }
  if (connection == null) {
    throw new DatabaseUnavailable();
  }

  // 4. Apply safe logic
  Balance -= amount;
}

// 5. Adjust handlers in the calling code

Type 📝

[X] Manual

Safety 🛡️

This refactoring is safe if you apply it gradually and update your code with care.

You must ensure all thrown exceptions are caught at the proper architectural level.

Why is the Code Better? ✨

You make the code clearer and more predictable.

You express technical failures and business rules separately, taking corrective actions with different stakeholders.

You also reduce confusion for the caller and improve maintainability.

How Does it Improve the Bijection? 🗺️

This refactoring strengthens the mapping between real-world concepts and code representation.

In reality, business rule violations and technical failures are fundamentally different situations.

Business exceptions represent expected alternative flows in your domain model.

Technical exceptions represent unexpected system problems that break the execution environment.

By separating these concerns, your code more accurately reflects the real-world distinction between “business says no” and “system cannot proceed”.

Limitations ⚠️

You need discipline to maintain two hierarchies.

If you misuse them, the benefits are lost. You also need to communicate the contract clearly to the clients of your code.

You should also create your own integrity tests to enforce these rules.

Refactor with AI 🤖

Suggested Prompt: 1. Identify business exceptions 2. Identify technical exceptions 3. Create two separate hierarchies 4. Update code to throw the right one 5. Adjust handlers accordingly

Without Proper Instructions 📵

• ChatGPT
• Claude
• Perplexity
• Copilot
• You
• Gemini
• DeepSeek
• Meta AI
• Grok
• Qwen

With Specific Instructions 👩‍🏫

• ChatGPT
• Claude
• Perplexity
• Copilot
• You
• Gemini
• DeepSeek
• Meta AI
• Grok
• Qwen

Tags 🏷️

• Exceptions

Level 🔋

[X] Intermediate

Related Refactorings 🔄

https://www.linkedin.com/pulse/refactoring-004-remove-unhandled-exceptions-maximiliano-contieri-ebhzf?embedable=true

Credits 🙏

Image by Ottó on Pixabay

This article is part of the Refactoring Series.

https://www.linkedin.com/pulse/how-improve-your-code-easy-refactorings-maximiliano-contieri?embedable=true