Custom Exceptions in Java — Error Codes That Actually Debug

package io.thecodeforge.exception;

public class InsufficientFundsException extends RuntimeException {
    private final String transactionId;
    private final double currentBalance;
    private final double attemptedAmount;

    public InsufficientFundsException(String transactionId, double currentBalance, double attemptedAmount) {
        super(String.format("Transaction %s failed: balance %.2f insufficient for %.2f",
                transactionId, currentBalance, attemptedAmount));
        this.transactionId = transactionId;
        this.currentBalance = currentBalance;
        this.attemptedAmount = attemptedAmount;
    }

    public String getTransactionId() { return transactionId; }
    public double getCurrentBalance() { return currentBalance; }
    public double getAttemptedAmount() { return attemptedAmount; }
}

package io.thecodeforge.exception;

import java.util.stream.Stream;

public class CheckedVsUncheckedDemo {
    // Checked – callers must handle
    static class ConfigFileNotFoundException extends Exception {
        public ConfigFileNotFoundException(String path) {
            super("Configuration file not found: " + path);
        }
    }

    // Unchecked – callers can ignore
    static class InvalidConfigFormatException extends RuntimeException {
        public InvalidConfigFormatException(String detail) {
            super("Invalid configuration format: " + detail);
        }
    }

    public static void main(String[] args) {
        // Lambda can't throw checked exception directly
        Stream.of("prod.properties", "dev.properties")
                .map(path -> {
                    try {
                        return loadConfig(path); // throws checked
                    } catch (ConfigFileNotFoundException e) {
                        throw new RuntimeException(e); // ugly workaround
                    }
                })
                .forEach(System.out::println);

        // Unchecked exception works cleanly in lambdas
        Stream.of("key=value", ":badformat")
                .forEach(CheckedVsUncheckedDemo::parseConfig);
    }

    static String loadConfig(String path) throws ConfigFileNotFoundException {
        // ... would actually read file
        return "loaded";
    }

    static void parseConfig(String line) {
        if (!line.contains("=")) {
            throw new InvalidConfigFormatException("Missing '=' in: " + line);
        }
    }
}

package io.thecodeforge.exception;

import java.time.Instant;

public abstract class PaymentException extends RuntimeException {
    private final String errorCode;
    private final Instant timestamp;

    protected PaymentException(String errorCode, String message) {
        super(message);
        this.errorCode = errorCode;
        this.timestamp = Instant.now();
    }

    public String getErrorCode() { return errorCode; }
    public Instant getTimestamp() { return timestamp; }
}

class InsufficientFundsException extends PaymentException {
    public InsufficientFundsException(String transactionId) {
        super("INSUFFICIENT_FUNDS", 
              "Transaction " + transactionId + " failed: insufficient funds");
    }
}

class CardDeclinedException extends PaymentException {
    private final String declineReason;
    public CardDeclinedException(String transactionId, String declineReason) {
        super("CARD_DECLINED", 
              "Transaction " + transactionId + " declined: " + declineReason);
        this.declineReason = declineReason;
    }
    public String getDeclineReason() { return declineReason; }
}

package io.thecodeforge.exception;

import java.util.UUID;

public class EmployeeService {
    // Factory method pattern for exceptions
    public static EmployeeNotFoundException notFound(UUID employeeId) {
        return new EmployeeNotFoundException(employeeId, 
               "Employee not found with id: " + employeeId);
    }

    public Employee getEmployee(UUID id) {
        // ... database lookup
        if (/* not found */ true) {
            throw notFound(id);
        }
        return null;
    }
}

class EmployeeNotFoundException extends RuntimeException {
    private static final String ERR_CODE = "EMP_NOT_FOUND";
    private final UUID employeeId;

    EmployeeNotFoundException(UUID employeeId, String message) {
        super(message);
        this.employeeId = employeeId;
    }

    public String getErrorCode() { return ERR_CODE; }
    public UUID getEmployeeId() { return employeeId; }
}

package io.thecodeforge.exception;

import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.*;

class InsufficientFundsExceptionTest {

    @Test
    void constructor_shouldSetFields() {
        InsufficientFundsException ex =
                new InsufficientFundsException("TXN-001", 50.0, 100.0);
        assertEquals("TXN-001", ex.getTransactionId());
        assertEquals(50.0, ex.getCurrentBalance(), 0.001);
        assertEquals(100.0, ex.getAttemptedAmount(), 0.001);
        assertTrue(ex.getMessage().contains("TXN-001"));
        assertTrue(ex.getMessage().contains("50.0"));
    }

    @Test
    void catchByType_works() {
        assertThrows(InsufficientFundsException.class, () -> {
            // Simulate a method that throws this exception
            throw new InsufficientFundsException("TXN-002", 100, 200);
        });
    }
}