Exception Handling in REST Services

Validation Note

The validation annotations @NotEmpty and @NotBlank cannot be applied to int or Integer type fields.They are only valid for CharSequence, Collection, Map, or Array types, not numeric types.

1. Exception Handling Overview

In Spring Boot REST APIs, exception handling can be centralized using @ControllerAdvice and @ExceptionHandler.These annotations separate exception-handling logic from the business logic in controllers.

2. Controller Advice Class

• A class annotated with @ControllerAdvice
• Contains methods annotated with @ExceptionHandler
• Acts as a centralized/global exception handler for all controllers
• Used to handle exceptions globally as part of a request lifecycle
• Can handle specific exception types via separate @ExceptionHandler methods

3. Exception Handler Methods

An exception handler method is defined inside either a controller or a controller advice class.

Rules

• The return type should be ResponseEntity<?>
• Inside @ExceptionHandler, specify which exception(s) to handle.
• The method can accept:
  • The exception type as a parameter.
  • Optionally, an HttpServletRequest argument for request-specific details.

Example

@ExceptionHandler(ResourceNotFoundException.class)
public ResponseEntity<String> handleResourceNotFound(
    ResourceNotFoundException ex, HttpServletRequest request) {
    return ResponseEntity.status(HttpStatus.NOT_FOUND).body("Resource not found: " + ex.getMessage());
}

4. Default (Catch-All) Exception Handler

If no specific exception type is defined, a generic handler can be used to catch all unhandled exceptions — acting as a fallback

@ExceptionHandler(Exception.class)
public ResponseEntity<String> handleException(Exception ex) {
    return ResponseEntity.internalServerError().body("An unexpected error occurred. Please try again later.");
}

5. Scope of Exception Handling

If define an @ExceptionHandler method

Level	Location	Scope	Description
Controller-level	Inside controller	Local	only handles exceptions thrown by that controller.
Global-level	Inside @ControllerAdvice	Application-wide	handles exceptions thrown by any controller in the application.

6. Exception Handling Flow

• If an exception occurs inside a controller:
  • Spring first checks if that controller has a local @ExceptionHandler method for that exception.
• If not found:
  • Spring then looks for a matching handler in any @ControllerAdvice class.
• If still not found:
  • A default Spring error response is returned.

↑ Back to top

Github Code : Exception Handling