Spring Boot 4 Microservices & REST APIs · Lesson

@ControllerAdvice and @ExceptionHandler

Handle exceptions globally.

@ControllerAdvice and @ExceptionHandler is a free Spring Boot 4 Microservices & REST APIs lesson on CoddyKit — lesson 3 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Spring Boot 4 Microservices & REST APIs learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

The Problem with Scattered Try/Catch

Handling errors with try/catch in every controller duplicates code and produces inconsistent responses. Spring MVC offers a centralized model: exception handlers that turn exceptions into clean HTTP responses.

Local @ExceptionHandler

A method annotated @ExceptionHandler inside a controller handles the listed exception types for that controller. It maps an exception to a response.

@RestController
public class OrderController {
    @ExceptionHandler(OrderNotFoundException.class)
    public ResponseEntity<String> handleNotFound(OrderNotFoundException ex) {
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(ex.getMessage());
    }
}

Going Global with @ControllerAdvice

@ControllerAdvice (or @RestControllerAdvice) hosts exception handlers that apply across all controllers. This centralizes error handling in one class.

@RestControllerAdvice
public class GlobalExceptionHandler {
    // handlers shared by every controller
}

Handling a Domain Exception

Define handlers for your own exceptions, returning the right status and a structured body. The same logic now serves every endpoint.

@RestControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(ResourceNotFoundException.class)
    @ResponseStatus(HttpStatus.NOT_FOUND)
    public ApiError notFound(ResourceNotFoundException ex) {
        return new ApiError("NOT_FOUND", ex.getMessage());
    }
}

A Consistent Error DTO

Return a uniform error shape so clients can parse failures predictably. Include a code, a human message, and optionally a timestamp and field details.

public record ApiError(
        String code,
        String message,
        Instant timestamp) {
    public ApiError(String code, String message) {
        this(code, message, Instant.now());
    }
}

Handling Validation Errors

Catch MethodArgumentNotValidException to convert Bean Validation failures into a clear, field-by-field response instead of Spring’s default body.

@ExceptionHandler(MethodArgumentNotValidException.class)
@ResponseStatus(HttpStatus.BAD_REQUEST)
public Map<String, String> handleValidation(MethodArgumentNotValidException ex) {
    Map<String, String> errors = new HashMap<>();
    ex.getBindingResult().getFieldErrors()
        .forEach(e -> errors.put(e.getField(), e.getDefaultMessage()));
    return errors;
}

A Catch-All Handler

Add a handler for Exception as a safety net, returning 500 with a generic message. Crucially, log the real exception but never leak stack traces to clients.

@ExceptionHandler(Exception.class)
@ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
public ApiError handleUnexpected(Exception ex) {
    log.error("Unhandled error", ex);
    return new ApiError("INTERNAL_ERROR", "Something went wrong");
}

Handler Selection Order

Spring picks the handler whose exception type most closely matches the thrown exception. A handler for OrderNotFoundException beats one for its superclass, so specific handlers take priority.

Scoping the Advice

You can narrow a @ControllerAdvice to specific packages, annotations, or controller types, allowing different error policies for, say, public vs internal APIs.

@RestControllerAdvice(basePackages = "com.example.api.publicapi")
public class PublicApiExceptionHandler { }

Accessing the Request

Handler methods can accept extra parameters like WebRequest or HttpServletRequest to enrich responses with the path or a correlation id.

@ExceptionHandler(ResourceNotFoundException.class)
public ApiError notFound(ResourceNotFoundException ex, HttpServletRequest req) {
    return new ApiError("NOT_FOUND", ex.getMessage() + " at " + req.getRequestURI());
}

Security: Do Not Over-Share

Error responses are a common information-leak vector. Return enough for clients to act, but never expose internal class names, SQL, or stack traces. Log details server-side instead.

Quick Check

Test your understanding of centralized handling.

Recap

Centralize error handling.

@ExceptionHandler maps exceptions to responses
@ControllerAdvice applies handlers across all controllers
Return a consistent error DTO
Handle validation, domain, and catch-all cases
Most specific handler wins; never leak internals to clients

Frequently asked questions

Is the “@ControllerAdvice and @ExceptionHandler” lesson free?

Yes — the full text of “@ControllerAdvice and @ExceptionHandler” is free to read here on the web, and the Spring Boot 4 Microservices & REST APIs course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Spring Boot 4 Microservices & REST APIs course, upgrade to CoddyKit PRO.

What will I learn in “@ControllerAdvice and @ExceptionHandler”?

Handle exceptions globally. You practise Spring Boot 4 Microservices & REST APIs with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Spring Boot 4 Microservices & REST APIs?

No prior experience is required. Spring Boot 4 Microservices & REST APIs on CoddyKit is structured for beginners through advanced learners; this is — lesson 3 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “@ControllerAdvice and @ExceptionHandler” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Spring Boot 4 Microservices & REST APIs lesson?

Yes. Every Spring Boot 4 Microservices & REST APIs lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to Spring Boot 4 Microservices & REST APIs