Error Handling Patterns

Error Handling — Beyond "Wrap It in a Try/Catch"

Good error handling means three things happening consistently across an entire codebase: exceptions that tell the caller what actually went wrong (not just "something failed"), an API response shape that's the same for every error regardless of which controller threw it, and enough logged context to diagnose an incident without needing to reproduce it.

// BEFORE — the client gets a raw stack trace, a different JSON shape
// from every controller, and the log line says nothing useful
$ curl -X POST /api/orders -d '{"customerId": 999}'
< 500 Internal Server Error
< java.lang.NullPointerException: Cannot invoke "Customer.hasOutstandingDebt()"
<     at com.shop.order.OrderService.validateBusinessRules(OrderService.java:42)
<     at com.shop.order.OrderService.createOrder(OrderService.java:18)
<     ... 47 more

// AFTER — a translated domain exception, a standard RFC 9457 shape,
// and a log line with the actual context
$ curl -X POST /api/orders -d '{"customerId": 999}'
< 404 Not Found
< Content-Type: application/problem+json
< {
<   "type": "https://api.shop.com/errors/entity-not-found",
<   "title": "Entity Not Found",
<   "status": 404,
<   "detail": "Customer not found with id: 999",
<   "instance": "/api/orders"
< }

Exception Hierarchy Strategy

Organize exceptions in a hierarchy that reflects your domain, not the technology that happened to trigger the failure.

// Base exception for the application — unchecked, so the rollback
// behavior covered in Transactions applies automatically by default
public class ApplicationException extends RuntimeException {
    private final ErrorCode errorCode;

    public ApplicationException(ErrorCode code, String message) {
        super(message);
        this.errorCode = code;
    }

    public ApplicationException(ErrorCode code, String message, Throwable cause) {
        super(message, cause);
        this.errorCode = code;
    }

    public ErrorCode getErrorCode() { return errorCode; }
}

public class EntityNotFoundException extends ApplicationException {
    public EntityNotFoundException(String entityType, Object id) {
        super(ErrorCode.NOT_FOUND,
              String.format("%s not found with id: %s", entityType, id));
    }
}

public class BusinessRuleException extends ApplicationException {
    public BusinessRuleException(String message) {
        super(ErrorCode.BUSINESS_RULE_VIOLATION, message);
    }
}

Error Codes — mapped to both HTTP status and a ProblemDetail type URI

public enum ErrorCode {
    NOT_FOUND("entity-not-found", HttpStatus.NOT_FOUND),
    VALIDATION_FAILED("validation-failed", HttpStatus.BAD_REQUEST),
    BUSINESS_RULE_VIOLATION("business-rule-violation", HttpStatus.UNPROCESSABLE_ENTITY),
    INTERNAL_ERROR("internal-error", HttpStatus.INTERNAL_SERVER_ERROR);

    private final String slug;
    private final HttpStatus httpStatus;

    ErrorCode(String slug, HttpStatus httpStatus) {
        this.slug = slug;
        this.httpStatus = httpStatus;
    }

    public URI typeUri() {
        return URI.create("https://api.shop.com/errors/" + slug);
    }

    public HttpStatus httpStatus() { return httpStatus; }
}

Try-with-Resources

public List<String> readLines(Path path) throws IOException {
    try (BufferedReader reader = Files.newBufferedReader(path)) {
        return reader.lines().toList();
    }   // closed automatically, even on exception
}

// Custom AutoCloseable — never rethrow from close() itself
public class PooledConnection implements AutoCloseable {
    @Override
    public void close() {
        try {
            connection.close();
        } catch (SQLException e) {
            log.warn("Failed to close connection", e);   // log, don't rethrow here
        }
    }
}

Fail-Fast Principle

public class OrderService {

    public Order createOrder(OrderRequest request) {
        validateRequest(request);          // structural validation first
        validateBusinessRules(request);    // then business rules
        return processOrder(request);   // only reached once both have passed
    }

    private void validateRequest(OrderRequest request) {
        Objects.requireNonNull(request, "Request cannot be null");
        if (request.getItems().isEmpty()) {
            throw new ValidationException("Order must have at least one item");
        }
    }

    private void validateBusinessRules(OrderRequest request) {
        Customer customer = customerRepository.findById(request.getCustomerId())
            .orElseThrow(() -> new EntityNotFoundException("Customer", request.getCustomerId()));

        if (customer.hasOutstandingDebt()) {
            throw new BusinessRuleException("Cannot create order: customer has outstanding debt");
        }
    }
}

Optional for Nullable Returns

// GOOD — Optional makes "might not exist" part of the return type
public Optional<Customer> findByEmail(String email) {
    return Optional.ofNullable(customerMap.get(email));
}

public CustomerDto getCustomerProfile(String email) {
    return customerRepository.findByEmail(email)
        .map(this::toDto)
        .orElseThrow(() -> new EntityNotFoundException("Customer", email));
}

Global Exception Handling — RFC 9457 ProblemDetail

Every error response from this site's Spring examples uses ProblemDetail — the standard, RFC 9457-compliant error shape built into Spring since Spring 6 / Boot 3 — rather than a hand-rolled error record. A custom ErrorResponse class means every client integrating with the API has to learn your team's specific, one-off error shape; ProblemDetail is a shape any HTTP client library already knows how to parse.

@RestControllerAdvice
public class GlobalExceptionHandler {

    private static final Logger log = LoggerFactory.getLogger(GlobalExceptionHandler.class);

    @ExceptionHandler(EntityNotFoundException.class)
    public ProblemDetail handleNotFound(EntityNotFoundException ex) {
        log.debug("Entity not found: {}", ex.getMessage());

        ProblemDetail problem = ProblemDetail.forStatusAndDetail(
            ex.getErrorCode().httpStatus(), ex.getMessage());
        problem.setType(ex.getErrorCode().typeUri());
        problem.setTitle("Entity Not Found");
        return problem;
    }

    @ExceptionHandler(ValidationException.class)
    public ProblemDetail handleValidation(ValidationException ex) {
        ProblemDetail problem = ProblemDetail.forStatusAndDetail(
            ex.getErrorCode().httpStatus(), ex.getMessage());
        problem.setType(ex.getErrorCode().typeUri());
        problem.setTitle("Validation Failed");
        problem.setProperty("fieldErrors", ex.getFieldErrors());   // RFC 9457 extension member
        return problem;
    }

    @ExceptionHandler(Exception.class)
    public ProblemDetail handleGeneric(Exception ex) {
        log.error("Unexpected error", ex);   // full stack trace, server-side only

        // Never expose ex.getMessage() here — it can leak internal details.
        // The client gets a generic, safe detail string regardless of cause.
        ProblemDetail problem = ProblemDetail.forStatusAndDetail(
            HttpStatus.INTERNAL_SERVER_ERROR, "An unexpected error occurred");
        problem.setType(ErrorCode.INTERNAL_ERROR.typeUri());
        return problem;
    }
}

// Resulting response body — standard RFC 9457 fields (type, title, status,
// detail, instance) plus a custom "fieldErrors" extension member
{
  "type": "https://api.shop.com/errors/validation-failed",
  "title": "Validation Failed",
  "status": 400,
  "detail": "Validation failed",
  "instance": "/api/orders",
  "fieldErrors": [{ "field": "items", "message": "must not be empty" }]
}

Logging at the Right Level for Each Failure

public class PaymentService {
    private static final Logger log = LoggerFactory.getLogger(PaymentService.class);

    public void processPayment(Payment payment) {
        try {
            gateway.process(payment);

        } catch (GatewayTimeoutException e) {
            // Recoverable — WARN, not ERROR; and prefer @Retryable over a
            // hand-rolled RetryableException where the retry policy is simple
            log.warn("Payment gateway timeout, id={}", payment.getId());
            throw new RetryableException(e);

        } catch (PaymentDeclinedException e) {
            // An expected business outcome, not a system failure — INFO, not ERROR
            log.info("Payment declined: id={}, reason={}", payment.getId(), e.getReason());
            throw e;

        } catch (Exception e) {
            // Genuinely unexpected — ERROR, with the full stack trace
            log.error("Unexpected error processing payment: id={}", payment.getId(), e);
            throw new PaymentException("Failed to process payment", e);
        }
    }
}

See Logging Frameworks for the full level guidance and structured/JSON logging conventions — the short version here is that the severity of the log entry should match whether the failure is expected business behavior, a recoverable condition, or a genuine bug, not just "an exception was thrown."

Exception Translation at Architectural Boundaries

public class CustomerRepository {

    public Customer save(Customer customer) {
        try {
            return jpaRepository.save(customer);
        } catch (DataIntegrityViolationException e) {
            // Translate a low-level, framework-specific exception into a
            // domain exception the service layer actually understands
            throw new CustomerAlreadyExistsException(customer.getEmail(), e);
        }
    }
}

public class CustomerAlreadyExistsException extends ApplicationException {
    public CustomerAlreadyExistsException(String email, Throwable cause) {
        super(ErrorCode.VALIDATION_FAILED,
              "Customer already exists with email: " + email,
              cause);   // preserve the cause chain — never discard it
    }
}

This is what keeps OrderService from ever needing to know that persistence happens to be JPA, or that a duplicate key throws DataIntegrityViolationException specifically — the exact same decoupling the Dependency Inversion Principle argues for at the class level, applied to exception types. See SOLID Principles.

Anti-Patterns to Avoid

// BAD — empty catch block, silently swallows the failure
try {
    riskyOperation();
} catch (Exception e) {
    // nothing — this is exactly the "commits with corrupted state"
    // trap covered in Transactions
}

// BAD — catching Throwable catches OutOfMemoryError, StackOverflowError too
try {
    operation();
} catch (Throwable t) {
    // you almost never want to intercept a JVM-level Error
}

// BAD — exceptions used for ordinary, expected flow control
try {
    int value = Integer.parseInt(input);
} catch (NumberFormatException e) {
    value = 0;
}
// GOOD — validate first; parsing a value you already know is numeric
// never needs an exception path at all
value = input.matches("\\d+") ? Integer.parseInt(input) : 0;

// BAD — log and rethrow the same exception; the caller logs it again too
try {
    operation();
} catch (Exception e) {
    log.error("Error", e);
    throw e;   // duplicate log entries for one failure, every time this is called
}

// BAD — a bare, generic exception with no type to catch specifically
throw new Exception("Something went wrong");

// GOOD — a specific, catchable, self-documenting exception type
throw new InvalidOrderStateException(order.getId(), order.getStatus());

Best Practices and Common Pitfalls

Interview Questions