Exception Handling in Spring Boot

Welcome! In our previous lesson, we delved into the intricacies of data validation within Spring Boot REST APIs. Today, we're addressing a vital aspect of building resilient APIs: error handling. Proper error handling ensures that users receive meaningful feedback and that your application does not expose unnecessary details when something goes wrong.

Error handling in Spring Boot is critical for translating cryptic 500 Internal Server Error responses into more informative HTTP responses with appropriate status codes and messages. There are multiple approaches to handling errors in Spring Boot, each with its own use cases:

• @ExceptionHandler: This annotation allows you to handle exceptions at the controller level, providing fine-grained control over error handling within individual controllers.
• @ControllerAdvice: This annotation enables global exception handling across all controllers, promoting consistency and reusability of error handling logic throughout your application.
• ResponseStatusException: This is a programmatic way to throw HTTP status exceptions directly from your code, making it easy to return specific HTTP status codes and messages from within your controller methods.

Let's explore each of these methods in more detail.

The @ExceptionHandler annotation allows you to handle exceptions at the controller level. Here’s a code snippet demonstrating how to use it:

package com.codesignal;

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class TodoController {

    @GetMapping("/todos/{id}")
    public Todo getTodoById(@PathVariable Long id) {
        // Assume findTodoById(id) throws IllegalArgumentException if id is invalid
        return findTodoById(id);
    }

    @ExceptionHandler(IllegalArgumentException.class)
    public ResponseEntity<String> handleIllegalArgumentException(IllegalArgumentException ex) {
        return new ResponseEntity<>(ex.getMessage(), HttpStatus.BAD_REQUEST);
    }
}

Using @ExceptionHandler at the controller level is quick and easy, but it can lead to redundancy and inconsistency if multiple controllers need to handle the same types of exceptions.

For a more centralized approach, Spring Boot offers @ControllerAdvice. This allows you to handle exceptions globally across all controllers:

package com.codesignal;

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.ResponseStatus;

@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(IllegalArgumentException.class)
    public ResponseEntity<String> handleIllegalArgumentException(IllegalArgumentException ex) {
        return new ResponseEntity<>(ex.getMessage(), HttpStatus.BAD_REQUEST);
    }

    @ExceptionHandler(TodoNotFoundException.class)
    public ResponseEntity<String> handleTodoNotFoundException(TodoNotFoundException ex) {
        return new ResponseEntity<>(ex.getMessage(), HttpStatus.NOT_FOUND);
    }
}

@ControllerAdvice ensures consistency and reusability by centralizing error handling logic. However, it could make your error handling logic a bit less straightforward to track, especially for new developers joining the project.

Another approach is using ResponseStatusException, a programmatic way to throw HTTP status exceptions directly from your code:

package com.codesignal;

import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.server.ResponseStatusException;

@RestController
@RequestMapping("/todos")
public class TodoController {

    @GetMapping("/{id}")
    public Todo getTodoById(@PathVariable Long id) {
        Todo todo = findTodoById(id);
        if (todo == null) {
            throw new ResponseStatusException(HttpStatus.NOT_FOUND, "Todo not found");
        }
        return todo;
    }
}

ResponseStatusException is simple and direct, which makes it easy to use for straightforward cases. However, it may not be as flexible or reusable as other approaches and requires explicit handling in the controller logic.

When you send a GET HTTP request to the /todos/invalid-id endpoint now, you'll notice that the response might look like this:

{
    "timestamp": "2024-08-10T12:00:00.000+00:00",
    "status": 404,
    "error": "Not Found",
    "path": "/todos/invalid-id"
}

However, the message "Todo not found" that you specified isn't included. This is because the application property server.error.include-message is not set. By default, Spring doesn't return error messages to reduce the risk of exposing sensitive information.

To control whether the "message" field is included in error responses, you should set the server.error.include-message property in the application.properties file. This property supports three values:

• always – The "message" field is always included in error responses.
• never – The "message" field is never included in error responses.
• on_param – The "message" field is included in error responses only if the request contains the parameter message=true. Otherwise, the response won't include the "message".

In the upcoming practice exercises, we'll set this property to always in the application.properties file to ensure the message is included in the response.

Understanding where exceptions can happen and the scope of their impact can guide you in choosing the right error handling technique:

• If an exception is specific to a method, use ResponseStatusException. This allows you to throw HTTP status exceptions directly from your code for straightforward case handling.
• If an exception is specific to a controller, use @ExceptionHandler at the controller level. This approach is quick and easy for handling exceptions localized to a single controller.
• If an exception can happen across multiple controllers, use @ControllerAdvice. This provides a centralized, reusable way to handle exceptions globally across all controllers.

We've covered essential error-handling techniques in Spring Boot, from @ExceptionHandler for controller-specific handling to @ControllerAdvice for global error management, and ResponseStatusException for in-code status handling. Each method has its strengths and is suited for different scenarios. Up next, you'll practice these concepts to ensure a solid understanding. Happy coding!