Click on any component in the diagram to explore its role in the global exception handling architecture.

Simulation Legend

Incoming HTTP Request

Exception Thrown / Bubbling

Standardized ProblemDetail JSON

HTTP Req

REST Client

Spring MVC Request Lifecycle

DispatcherServlet

Front Controller

@RestController

API Endpoints

@Service

Business Logic

Global Exception Handling

@RestControllerAdvice

Global Interceptor

@ExceptionHandler

(UserNotFoundEx.class)

@ExceptionHandler

(MethodArgNotValidEx.class)

ProblemDetail (RFC 7807)

Standardized Error JSON Payload

Spring Boot: Global Exception Handling

Building robust REST APIs isn't just about handling the happy path; it's about how gracefully your application fails. Unhandled exceptions result in generic 500 server errors with messy stack traces exposing internal architecture. Spring Boot provides a powerful, elegant way to handle errors globally.

Centralization

Don't clutter your `@RestController` methods with `try/catch` blocks. Separate business logic from error handling logic to adhere to the Single Responsibility Principle.

Standardization

Clients expect a consistent error format. Spring 3.0 introduced native support for RFC 7807 Problem Details, creating a universal JSON structure for HTTP API errors.

Core Components

1. @RestControllerAdvice

This annotation is a specialized `@Component` that allows you to consolidate your multiple, scattered `@ExceptionHandler`s into a single, global error handling component.

@RestControllerAdvice
public class GlobalExceptionHandler {
    // Exception handlers go here
}

2. Handling Custom Business Exceptions (e.g., 404 Not Found)

When your service layer throws a `UserNotFoundException`, the dispatcher routes it here. We map it to a 404 Not Found status and return a `ProblemDetail`.

@ExceptionHandler(UserNotFoundException.class)
public ProblemDetail handleUserNotFoundException(UserNotFoundException ex) {
    ProblemDetail problemDetail = ProblemDetail.forStatusAndDetail(
            HttpStatus.NOT_FOUND, 
            ex.getMessage()
    );
    problemDetail.setTitle("User Not Found");
    problemDetail.setType(URI.create("https://api.example.com/errors/not-found"));
    problemDetail.setProperty("timestamp", Instant.now());
    
    return problemDetail;
}

3. Handling Validation Exceptions (e.g., 400 Bad Request)

When a client sends bad data that fails `@Valid` checks, Spring throws a `MethodArgumentNotValidException`. We can catch this, extract the specific field errors, and append them to our `ProblemDetail`.

@ExceptionHandler(MethodArgumentNotValidException.class)
public ProblemDetail handleValidationErrors(MethodArgumentNotValidException ex) {
    ProblemDetail problemDetail = ProblemDetail.forStatusAndDetail(
            HttpStatus.BAD_REQUEST, 
            "Request validation failed"
    );
    
    // Extract field-level errors
    List<Map<String, String>> fieldErrors = ex.getBindingResult().getFieldErrors()
        .stream()
        .map(err -> Map.of(
            "field", err.getField(),
            "message", err.getDefaultMessage()
        )).toList();

    // Add custom property to RFC 7807 spec
    problemDetail.setProperty("invalid_params", fieldErrors);
    
    return problemDetail;
}

The RFC 7807 Output

The resulting JSON response looks exactly like the standardized spec demands:

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "Request validation failed",
  "instance": "/api/users",
  "invalid_params": [
    {
      "field": "email",
      "message": "must be a well-formed email address"
    }
  ]
}

The consumer of your API. It could be a React frontend, a mobile app, or another microservice.

The client expects structured, predictable responses. If an error occurs, it needs to know what went wrong (HTTP Status) and why (Error Body) so it can display appropriate UI to the user (e.g., highlighting invalid form fields).

The Front Controller of Spring MVC. All incoming HTTP requests come here first.

It routes requests to the correct `@RestController`. More importantly for this flow, if an exception is thrown anywhere in the controller or service layer, it bubbles back up to the `DispatcherServlet`.

The DispatcherServlet uses a `HandlerExceptionResolver` to figure out which `@ExceptionHandler` method should process the thrown exception.

The entry point for your business logic.

Exceptions can originate here directly. For example, if you use `@Valid` on a `@RequestBody` parameter and the validation fails, Spring automatically throws a `MethodArgumentNotValidException` right before your controller method even executes.

Where your core business logic and database interactions happen.

This is where custom business exceptions are usually thrown. For example, if a database query `findById` returns empty, the service throws a `UserNotFoundException`. This exception bubbles up through the controller back to the dispatcher.

A specialized form of `@ControllerAdvice` combining it with `@ResponseBody`.

It acts as an interceptor that surrounds the logic of all your controllers. By placing your `@ExceptionHandler` methods inside this class, you ensure that if an exception occurs in any controller, this class will handle it globally.

A method specifically designated to catch a particular Exception type (e.g., `UserNotFoundException`).

Instead of the app crashing, Spring invokes this method. You write code here to convert the raw exception into a clean `ProblemDetail` object with a `404 Not Found` HTTP status code.

Handles validation failures (`MethodArgumentNotValidException`).

This handler extracts the `BindingResult` from the exception, iterates through the field-level validation errors (e.g., "Email is invalid", "Password too short"), and adds them to a custom list inside the standard ProblemDetail JSON.

Introduced in Spring Framework 6 (Spring Boot 3), this class represents an RFC 7807 "Problem Details for HTTP APIs" payload.

It standardizes error responses with fields like:

type: URI identifying the problem type.
title: Short summary.
status: HTTP status code.
detail: Human-readable explanation.
instance: URI of the specific occurrence.

Global Exception Handling Flow

Component Inspector