REST Error Handling with @ControllerAdvice and ProblemDetail

//ErrorHandlingApp.java
package com.javabrahman.rest.errors;

import jakarta.validation.Valid;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Positive;
import java.math.BigDecimal;
import java.net.URI;
import java.util.Map;
import java.util.TreeMap;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.http.HttpStatusCode;
import org.springframework.http.ProblemDetail;
import org.springframework.http.ResponseEntity;
import org.springframework.web.ErrorResponseException;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.context.request.WebRequest;
import org.springframework.web.servlet.mvc.method.annotation.ResponseEntityExceptionHandler;

// A plain domain exception: knows nothing about HTTP
class BookNotFoundException extends RuntimeException {
  final long id;

  BookNotFoundException(long id) {
    super("No book with id " + id);
    this.id = id;
  }
}

// An exception that describes its own HTTP response
class OutOfStockException extends ErrorResponseException {
  OutOfStockException(String title) {
    super(HttpStatus.CONFLICT, problem(title), null);
  }

  private static ProblemDetail problem(String title) {
    ProblemDetail pd = ProblemDetail.forStatusAndDetail(HttpStatus.CONFLICT, "'" + title + "' is out of stock");
    pd.setType(URI.create("https://api.example.com/problems/out-of-stock"));
    pd.setTitle("Out of stock");
    pd.setProperty("restockExpected", "2026-11-20");
    return pd;
  }
}

record NewBook(@NotBlank String title, @Positive BigDecimal price) {
}

@RestController
@RequestMapping("/api/books")
class BookController {

  @GetMapping("/{id}")
  String one(@PathVariable long id) {
    if (id != 1) {
      throw new BookNotFoundException(id);
    }
    return "Effective Java";
  }

  @PostMapping
  String create(@Valid @RequestBody NewBook book) {
    return "created " + book.title();
  }

  @PostMapping("/{id}/orders")
  String order(@PathVariable long id) {
    throw new OutOfStockException("Effective Java");
  }

  @GetMapping("/report")
  String report() {
    throw new IllegalStateException("Connection to db.internal:5432 refused for user shop_admin");
  }
}

@RestControllerAdvice
class ApiExceptionHandler extends ResponseEntityExceptionHandler {
  private static final Logger log = LoggerFactory.getLogger(ApiExceptionHandler.class);

  // 1. A domain exception becomes a 404 problem
  @ExceptionHandler(BookNotFoundException.class)
  ProblemDetail bookNotFound(BookNotFoundException e) {
    ProblemDetail pd = ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, e.getMessage());
    pd.setType(URI.create("https://api.example.com/problems/book-not-found"));
    pd.setTitle("Book not found");
    pd.setProperty("bookId", e.id);
    return pd;
  }

  // 2. Validation errors: Spring's standard problem, plus the field errors
  @Override
  protected ResponseEntity<Object> handleMethodArgumentNotValid(MethodArgumentNotValidException e,
      HttpHeaders headers, HttpStatusCode status, WebRequest request) {
    ProblemDetail pd = e.getBody();   // status 400, title "Bad Request", detail "Invalid request content."
    Map<String, String> errors = new TreeMap<>();
    e.getBindingResult().getFieldErrors().forEach(error -> errors.put(error.getField(), error.getDefaultMessage()));
    pd.setProperty("errors", errors);
    return handleExceptionInternal(e, pd, headers, status, request);
  }

  // 3. Anything else: log it, and tell the client as little as possible
  @ExceptionHandler(Exception.class)
  ProblemDetail unexpected(Exception e) {
    log.error("Unexpected error", e);
    return ProblemDetail.forStatusAndDetail(HttpStatus.INTERNAL_SERVER_ERROR,
        "An unexpected error occurred. It has been logged and will be looked at.");
  }
}

@SpringBootApplication
public class ErrorHandlingApp {
  public static void main(String[] args) {
    SpringApplication.run(ErrorHandlingApp.class, args);
  }
}