Centralized Exception Handling with @ControllerAdvice

1. From Scattered try-catch to Centralized Control

Imagine a service with multiple controller methods. Without a centralized strategy, you might handle exceptions directly inside each method:

@PostMapping("/withdraw")
public ResponseEntity<?> withdraw(@RequestBody WithdrawRequest request) {
    try {
        TransactionDto dto = accountService.withdraw(request.getAccountId(), request.getAmount());
        return ResponseEntity.ok(dto);
    } catch (AccountNotFoundException e) {
        // Duplicated error handling logic
        ApiError error = new ApiError("ACCOUNT_NOT_FOUND", e.getMessage());
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(error);
    } catch (InsufficientBalanceException e) {
        // More duplicated logic
        ApiError error = new ApiError("INSUFFICIENT_BALANCE", e.getMessage());
        return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(error);
    }
}

This approach has several significant problems:

• Code Duplication: The same error-handling logic is repeated across many controllers and methods.
• Inconsistency: Different developers might create slightly different error response formats, leading to an inconsistent API.
• Cluttered Business Logic: The core purpose of the controller method is obscured by verbose error handling.

A first step to improve this is using @ExceptionHandler within the controller class. However, this only solves the problem for a single controller. The truly scalable, enterprise-grade solution is to centralize this logic for the entire application.

2. Building a Global Exception Handler with @RestControllerAdvice

Spring provides a powerful mechanism for this: @ControllerAdvice. When you annotate a class with @ControllerAdvice, you are creating a global, AOP-style interceptor that can handle exceptions from any controller.

For REST APIs, it's even better to use @RestControllerAdvice, which is a convenience annotation that combines @ControllerAdvice and @ResponseBody. This ensures that the return values from your handler methods are automatically serialized to the response body (e.g., as JSON).

A production-grade global exception handler typically has three components:

1. Custom Exception Classes: For specific business rule violations (e.g., ResourceNotFoundException).
2. A Standardized Error DTO: A consistent JSON structure for all error responses.
3. The Handler Class: The @RestControllerAdvice class containing @ExceptionHandler methods.

Let's see how to implement these pieces.

Now that you have the building blocks—a way to signal a specific error (ResourceNotFoundException) and a structure to communicate it (ErrorResponse)—let's create the central handler itself.

As you've seen, this pattern dramatically cleans up your controllers. They can now focus exclusively on their primary logic, throwing exceptions when rules are violated, confident that a global handler will catch them and produce a consistent, well-formed error response.

Your controller method becomes simple and readable:

@GetMapping("/products/{id}")
public String getProductById(@PathVariable int id) {
    if (id != 1) {
        // Just throw the exception. The GlobalExceptionHandler will take care of the rest.
        throw new ResourceNotFoundException("Product with ID " + id + " not found.");
    }
    return "Product ID: " + id;
}

3. Fine-Tuning: Status Codes and Logging

Controlling HTTP Status Codes

You have two primary ways to associate an HTTP status code with an exception:

1. @ResponseStatus on the Exception Class:

   @ResponseStatus(HttpStatus.NOT_FOUND)
   public class ResourceNotFoundException extends RuntimeException { ... }
   

   This is simple and declarative. The handler method for this exception no longer needs to return a ResponseEntity. However, it's static—a ResourceNotFoundException will always result in a 404.

2. Returning ResponseEntity from the Handler:

   @ExceptionHandler(ResourceNotFoundException.class)
   public ResponseEntity<ErrorResponse> handleNotFound(...) {
       // ... create ErrorResponse object
       return new ResponseEntity<>(error, HttpStatus.NOT_FOUND);
   }
   

   This is more flexible and is generally the preferred approach in complex applications. It makes the handler's behavior explicit and allows you to return different status codes based on the exception's contents if needed.

Don't Forget to Log!

A user-facing error message should be clean and simple ("Something went wrong"). However, for your internal diagnostics, you need the full story. The global exception handler is the perfect place to log the full stack trace for unexpected errors.

@RestControllerAdvice
public class GlobalExceptionHandler {

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

    // ... other handlers for specific exceptions

    @ExceptionHandler(Exception.class)
    public ResponseEntity<ErrorResponse> handleGeneric(Exception ex, HttpServletRequest request) {
        // Log the full stack trace for developers
        logger.error("An unexpected error occurred: Request URL [{}]", request.getRequestURI(), ex);

        // Return a generic, safe response to the client
        ErrorResponse error = new ErrorResponse(
            HttpStatus.INTERNAL_SERVER_ERROR.value(),
            "Internal Server Error",
            "An unexpected error occurred. Please contact support.",
            request.getRequestURI()
        );
        return new ResponseEntity<>(error, HttpStatus.INTERNAL_SERVER_ERROR);
    }
}

This ensures you never leak sensitive implementation details or stack traces to the client, while still capturing all necessary information for debugging.

@ExceptionHandler(InvalidOperationException.class)
public ResponseEntity<ErrorResponse> handleInvalidOperation(InvalidOperationException ex, HttpServletRequest request) {
    ErrorResponse error = new ErrorResponse(
        HttpStatus.CONFLICT.value(),
        "Conflict",
        ex.getMessage(), // The message from the thrown exception
        request.getRequestURI()
    );
    return new ResponseEntity<>(error, HttpStatus.CONFLICT);
}

4. Preparing for the Interview

Exception handling is a frequent topic in Spring interviews. Being able to discuss these patterns clearly and confidently is key. Let's review some common questions.

These questions test your understanding of the core mechanics. A senior-level candidate would also be expected to discuss the why—the design principles of consistency, maintainability, and separation of concerns that motivate this pattern.

Conclusion

In this lesson, you've mastered a fundamental pattern for building professional REST APIs in Spring Boot. By centralizing your exception handling, you create a system that is more robust, easier to maintain, and provides a predictable and consistent experience for your API consumers.

Key Takeaways:

• Centralize with @RestControllerAdvice: Avoid try-catch blocks in controllers by creating a global handler.
• Standardize Responses: Use a dedicated error DTO (e.g., ErrorResponse) to ensure all error messages have a consistent structure.
• Handle Specificity: Create specific handlers for custom business exceptions (ResourceNotFoundException), framework exceptions (MethodArgumentNotValidException), and a generic fallback for Exception.class.
• Control the Status: Use ResponseEntity in your handler methods to gain explicit control over the HTTP status code.
• Log for Yourself, Not the User: Log detailed stack traces for unexpected errors in your handler, but return clean, safe messages to the client.

Preview of the Next Lesson:

We have now completed our module on Spring & Spring Boot Core, covering IoC, beans, validation, and exception handling. We are now ready to move to the persistence layer. In the next lesson, we will begin the "Spring Data & Transaction Management" module by exploring one of its core concepts: Explain the JPA entity lifecycle and the role of the persistence context. This will be your first step into understanding how Spring manages data and interacts with the database.