Global Exception Handling & Uniform Errors

Why one central handler?

In the last lesson you saw @RestControllerAdvice catch one exception type. The real power is bigger: it lets you handle every error from every controller in one class, so all your errors come back in the same shape. That consistency is what separates a hobby API from a professional one.

Imagine a front-end developer using your API. If a 404 returns {"error":"..."}, a validation error returns a Spring default blob, and a server error returns a stack trace, they have to handle three different shapes. With a global handler, every error looks the same, so they write the error-handling code once.

Step 1: define one error shape

First decide the JSON every error will use. A small DTO does the job — a timestamp, a status code, and a message:

public class ApiError {
    private Instant timestamp = Instant.now();
    private int status;
    private String message;
    public ApiError(int status, String message) {
        this.status = status; this.message = message;
    }
    // getters ...
}

Step 2: the global handler

Now one @RestControllerAdvice class catches the different error types and turns each into an ApiError with the right status. ResponseEntity lets us set both the body and the HTTP status:

@RestControllerAdvice
public class GlobalExceptionHandler {

    // 404 — our own "not found" exception
    @ExceptionHandler(NotFoundException.class)
    public ResponseEntity<ApiError> handleNotFound(NotFoundException ex) {
        ApiError body = new ApiError(404, ex.getMessage());
        return ResponseEntity.status(404).body(body);
    }

    // 400 — bean validation failures (@Valid)
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ApiError> handleValidation(MethodArgumentNotValidException ex) {
        String msg = ex.getBindingResult().getFieldErrors().stream()
            .map(e -> e.getField() + ": " + e.getDefaultMessage())
            .collect(Collectors.joining(", "));
        return ResponseEntity.status(400).body(new ApiError(400, msg));
    }

    // 500 — the safety net for anything unexpected
    @ExceptionHandler(Exception.class)
    public ResponseEntity<ApiError> handleAny(Exception ex) {
        return ResponseEntity.status(500)
            .body(new ApiError(500, "Something went wrong"));
    }
}

How a request error flows through the handler

1. A controller method throws an exception (or @Valid rejects the body).
2. Instead of crashing to the client, Spring looks for a matching @ExceptionHandler in any @RestControllerAdvice.
3. It finds the most specific match — NotFoundException for a missing record, MethodArgumentNotValidException for a validation failure, or the Exception catch-all for anything else.
4. That handler builds an ApiError and returns it with the right status.
5. The client always receives the same JSON shape, so it can handle every error the same way.