@ExceptionHandler in Spring MVC — Handling Specific Exceptions

Direct Answer

@ExceptionHandler maps one or more exception types to a handler method in a controller or applicable @ControllerAdvice. Local handlers are useful for controller-specific behavior; advice is useful for a shared API contract. Neither placement is always superior. The most specific applicable exception mapping is preferred according to Spring's resolver rules.

Code Example

// LOCAL SCOPE - only handles exceptions from OrderController
@RestController
@RequestMapping("/api/orders")
public class OrderController {

    @GetMapping("/{id}")
    public Order getOrder(@PathVariable Long id) {
        throw new OrderNotFoundException("Order " + id + " not found");
    }

    @ExceptionHandler(OrderNotFoundException.class)  // Only for this controller
    public ResponseEntity<String> handleNotFound(OrderNotFoundException ex) {
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(ex.getMessage());
    }
}

// GLOBAL SCOPE - handles exceptions from ALL controllers
@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(OrderNotFoundException.class)  // Applies everywhere
    public ResponseEntity<ErrorResponse> handleOrderNotFound(OrderNotFoundException ex, HttpServletRequest request) {
        var error = new ErrorResponse(404, ex.getMessage(), LocalDateTime.now(), request.getRequestURI());
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(error);
    }
}

record ErrorResponse(int status, String message, LocalDateTime timestamp, String path) {}

Common Mistakes & Pitfalls

• Thinking local handlers are global: Freshers often put @ExceptionHandler inside a @RestController expecting it to handle exceptions from all controllers — it only works for that one controller, leading to missed exceptions.
• Not returning proper HTTP status codes: Returning ResponseEntity.ok() from an exception handler defeats the purpose — clients need proper error status codes like 404, 400, or 500 to handle errors correctly.
• Handling too broadly: Writing @ExceptionHandler(Exception.class) in a local controller catches all exceptions from that controller, hiding bugs that should propagate to global handlers.
• Ignoring exception hierarchy: If you have @ExceptionHandler for both RuntimeException and IllegalArgumentException, Spring chooses the most specific match, but freshers often don't realize the order matters when exceptions inherit from each other.