Exception handling — @ExceptionHandler, @ControllerAdvice, Problem Details RFC 9457

@ResponseStatus(HttpStatus.NOT_FOUND)
public class OrderNotFoundException extends RuntimeException {
    public OrderNotFoundException(Long id) {
        super("Order " + id + " not found");
    }
}

@Service
public class OrderService {
    public OrderDto findById(Long id) {
        return repo.findById(id).orElseThrow(() -> new OrderNotFoundException(id));
    }
}

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(OrderNotFoundException.class)
    public ProblemDetail handleNotFound(OrderNotFoundException ex) {
        ProblemDetail pd = ProblemDetail.forStatus(HttpStatus.NOT_FOUND);
        pd.setTitle("Order not found");
        pd.setDetail(ex.getMessage());
        pd.setProperty("orderId", ex.getOrderId());
        return pd;
    }

    @ExceptionHandler(DuplicateOrderException.class)
    public ProblemDetail handleDuplicate(DuplicateOrderException ex) {
        ProblemDetail pd = ProblemDetail.forStatus(HttpStatus.CONFLICT);
        pd.setTitle("Duplicate order");
        pd.setDetail(ex.getMessage());
        return pd;
    }

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ProblemDetail handleValidation(MethodArgumentNotValidException ex) {
        ProblemDetail pd = ProblemDetail.forStatus(HttpStatus.BAD_REQUEST);
        pd.setTitle("Validation failed");
        pd.setDetail("Request body has invalid fields");

        List<Map<String, String>> violations = ex.getBindingResult().getAllErrors().stream()
            .map(err -> Map.of(
                "field", ((FieldError) err).getField(),
                "message", err.getDefaultMessage(),
                "rejectedValue", String.valueOf(((FieldError) err).getRejectedValue())
            ))
            .toList();
        pd.setProperty("violations", violations);

        return pd;
    }

    @ExceptionHandler(Exception.class)
    public ProblemDetail handleAll(Exception ex) {
        log.error("Unhandled exception", ex);
        ProblemDetail pd = ProblemDetail.forStatus(HttpStatus.INTERNAL_SERVER_ERROR);
        pd.setTitle("Internal server error");
        pd.setDetail("An unexpected error occurred. Please try again later.");
        // KHONG include stack trace — security
        return pd;
    }
}

@ExceptionHandler(RuntimeException.class)        // catch-all RuntimeException
public ... handleRuntime(RuntimeException ex) { ... }

@ExceptionHandler(OrderNotFoundException.class)   // specific
public ... handleNotFound(OrderNotFoundException ex) { ... }

@RestControllerAdvice(basePackages = "com.olhub.api.v1")           // chi v1
@RestControllerAdvice(annotations = ApiController.class)            // controller có annotation
@RestControllerAdvice(assignableTypes = {OrderController.class})   // class cụ thể

HTTP/1.1 404 Not Found
Content-Type: application/problem+json

{
  "type": "https://api.olhub.org/errors/order-not-found",
  "title": "Order not found",
  "status": 404,
  "detail": "Order 42 not found",
  "instance": "/api/v1/orders/42",
  "orderId": 42,
  "timestamp": "2026-04-15T10:00:00Z"
}

spring:
  mvc:
    problemdetails:
      enabled: true

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "Invalid request content.",
  "instance": "/api/v1/orders"
}

ProblemDetail pd = ProblemDetail.forStatus(HttpStatus.NOT_FOUND);

// Hoac voi message
ProblemDetail pd = ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, "Order 42 not found");

// Custom field
pd.setType(URI.create("https://api.olhub.org/errors/order-not-found"));
pd.setTitle("Order not found");
pd.setInstance(URI.create("/api/v1/orders/42"));
pd.setProperty("orderId", 42L);
pd.setProperty("timestamp", Instant.now());

https://api.olhub.org/errors/order-not-found

// Domain layer — POJO exception
public class OrderNotFoundException extends RuntimeException {
    private final Long orderId;
    public OrderNotFoundException(Long orderId) {
        super("Order " + orderId + " not found");
        this.orderId = orderId;
    }
    public Long getOrderId() { return orderId; }
}

public class InsufficientStockException extends RuntimeException {
    private final String sku;
    private final int requested;
    private final int available;
    // ...
}

public class PaymentDeclinedException extends RuntimeException { ... }

public class InvalidOrderStateException extends RuntimeException { ... }

// Web layer — mapping exception → HTTP status
@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(OrderNotFoundException.class)
    public ProblemDetail handleNotFound(OrderNotFoundException ex) {
        return problem(HttpStatus.NOT_FOUND, "Order not found", ex.getMessage())
            .property("orderId", ex.getOrderId());
    }

    @ExceptionHandler(InsufficientStockException.class)
    public ProblemDetail handleInsufficientStock(InsufficientStockException ex) {
        return problem(HttpStatus.CONFLICT, "Insufficient stock", ex.getMessage())
            .property("sku", ex.getSku())
            .property("requested", ex.getRequested())
            .property("available", ex.getAvailable());
    }

    @ExceptionHandler(PaymentDeclinedException.class)
    public ProblemDetail handlePaymentDeclined(PaymentDeclinedException ex) {
        return problem(HttpStatus.PAYMENT_REQUIRED, "Payment declined", ex.getMessage());
    }

    @ExceptionHandler(InvalidOrderStateException.class)
    public ProblemDetail handleInvalidState(InvalidOrderStateException ex) {
        return problem(HttpStatus.UNPROCESSABLE_ENTITY, "Invalid order state", ex.getMessage());
    }
}

private static ProblemDetailBuilder problem(HttpStatus status, String title, String detail) {
    return new ProblemDetailBuilder(status, title, detail);
}

@GetMapping("/orders/{id}")
public OrderDto get(@PathVariable Long id) {
    return orderService.findOptional(id)
        .orElseThrow(() -> new ResponseStatusException(
            HttpStatus.NOT_FOUND,
            "Order " + id + " not found"
        ));
}

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "Invalid request content.",
  "instance": "/api/v1/orders"
}

@ExceptionHandler(MethodArgumentNotValidException.class)
public ProblemDetail handleValidation(MethodArgumentNotValidException ex, HttpServletRequest req) {
    ProblemDetail pd = ProblemDetail.forStatus(HttpStatus.BAD_REQUEST);
    pd.setType(URI.create("https://api.olhub.org/errors/validation"));
    pd.setTitle("Validation failed");
    pd.setDetail("Request body has " + ex.getBindingResult().getErrorCount() + " invalid fields");
    pd.setInstance(URI.create(req.getRequestURI()));

    List<Map<String, Object>> violations = ex.getBindingResult().getFieldErrors().stream()
        .map(err -> {
            Map<String, Object> v = new LinkedHashMap<>();
            v.put("field", err.getField());
            v.put("message", err.getDefaultMessage());
            v.put("rejectedValue", err.getRejectedValue());
            return v;
        })
        .toList();
    pd.setProperty("violations", violations);

    return pd;
}

{
  "type": "https://api.olhub.org/errors/validation",
  "title": "Validation failed",
  "status": 400,
  "detail": "Request body has 2 invalid fields",
  "instance": "/api/v1/orders",
  "violations": [
    {"field": "customer", "message": "must not be blank", "rejectedValue": ""},
    {"field": "total", "message": "must be positive", "rejectedValue": -10}
  ]
}

// ANTI-PATTERN
@ExceptionHandler(Exception.class)
public ProblemDetail handleAll(Exception ex) {
    ProblemDetail pd = ProblemDetail.forStatus(500);
    pd.setDetail(ex.getMessage());
    pd.setProperty("stackTrace", ExceptionUtils.getStackTrace(ex));  // KHONG BAO GIO
    return pd;
}

@ExceptionHandler(Exception.class)
public ProblemDetail handleAll(Exception ex) {
    String requestId = MDC.get("requestId");
    log.error("Unhandled exception, requestId={}", requestId, ex);     // log SERVER, không client

    ProblemDetail pd = ProblemDetail.forStatus(500);
    pd.setTitle("Internal server error");
    pd.setDetail("An unexpected error occurred. Please contact support with request ID.");
    pd.setProperty("requestId", requestId);     // client xem requestId, lien he support
    return pd;
}

spring:
  mvc:
    problemdetails:
      enabled: true
server:
  error:
    include-stacktrace: on_param      # ?trace=true → include (chỉ dev)
    include-binding-errors: on_param
    include-message: always

@WebMvcTest(OrderController.class)
class OrderControllerTest {

    @Autowired MockMvc mockMvc;
    @MockitoBean OrderService orderService;

    @Test
    void getNonExistent_returns404() throws Exception {
        when(orderService.findById(99L))
            .thenThrow(new OrderNotFoundException(99L));

        mockMvc.perform(get("/api/v1/orders/99"))
            .andExpect(status().isNotFound())
            .andExpect(content().contentType("application/problem+json"))
            .andExpect(jsonPath("$.title").value("Order not found"))
            .andExpect(jsonPath("$.status").value(404))
            .andExpect(jsonPath("$.detail").value("Order 99 not found"))
            .andExpect(jsonPath("$.orderId").value(99));
    }

    @Test
    void invalidRequest_returns400WithViolations() throws Exception {
        String invalidJson = """
            { "customer": "", "total": -10 }
            """;

        mockMvc.perform(post("/api/v1/orders")
                .contentType(MediaType.APPLICATION_JSON)
                .content(invalidJson))
            .andExpect(status().isBadRequest())
            .andExpect(jsonPath("$.title").value("Validation failed"))
            .andExpect(jsonPath("$.violations", hasSize(2)));
    }
}

@RestControllerAdvice
@Slf4j
public class GlobalExceptionHandler {

    private final MeterRegistry meterRegistry;

    @ExceptionHandler(Exception.class)
    public ProblemDetail handleAll(Exception ex, HttpServletRequest req) {
        String requestId = MDC.get("requestId");
        log.error("Unhandled exception, path={}, requestId={}, exClass={}",
            req.getRequestURI(), requestId, ex.getClass().getSimpleName(), ex);

        // Increment metric voi label exception class
        meterRegistry.counter("api.exception",
            "exception", ex.getClass().getSimpleName(),
            "endpoint", req.getRequestURI(),
            "method", req.getMethod()).increment();

        ProblemDetail pd = ProblemDetail.forStatus(500);
        pd.setTitle("Internal server error");
        pd.setDetail("An unexpected error occurred. Contact support with requestId.");
        pd.setProperty("requestId", requestId);
        return pd;
    }
}

# 5xx spike — pages on-call
- alert: ServerErrorSpike
  expr: |
    sum(rate(http_server_requests_seconds_count{status=~"5.."}[5m]))
    /
    sum(rate(http_server_requests_seconds_count[5m]))
    > 0.01
  for: 5m
  labels:
    severity: critical
  annotations:
    summary: "5xx error rate above 1% on {{ $labels.application }}"

# 4xx anomaly — slack channel only
- alert: ClientErrorAnomaly
  expr: |
    sum(rate(http_server_requests_seconds_count{status=~"4.."}[5m]))
    > 2 * sum(rate(http_server_requests_seconds_count{status=~"4.."}[1h] offset 1d))
  for: 10m
  labels:
    severity: warning

# Specific exception class spike — early warning
- alert: PaymentDeclinedSpike
  expr: rate(api_exception_total{exception="PaymentDeclinedException"}[5m]) > 10
  for: 5m
  labels:
    severity: warning
    team: payments

@Test
void errorResponse_doesNotContainPii() throws Exception {
    when(orderService.findById(any())).thenThrow(
        new RuntimeException("DB error: user_email='[email protected]' duplicate"));

    String response = mockMvc.perform(get("/api/orders/42"))
        .andExpect(status().isInternalServerError())
        .andReturn().getResponse().getContentAsString();

    // Pattern PII — assert KHONG match trong response
    assertThat(response).doesNotMatch("\\b\\w+@\\w+\\.\\w+\\b");        // email
    assertThat(response).doesNotMatch("user_email|password|ssn");        // schema/keyword
}

@RestControllerAdvice
@Order(Ordered.LOWEST_PRECEDENCE)        // chay sau cung
public class FallbackHandler {

    @ExceptionHandler(Throwable.class)
    public ResponseEntity<String> ultimate(Throwable t) {
        // Khong dung Spring serialization, khong call MDC, khong meter
        // Defensive — chi tra response toi gian
        return ResponseEntity.status(500)
            .header("Content-Type", "application/problem+json")
            .body("{\"status\":500,\"title\":\"Internal Server Error\"}");
    }
}

throw new RuntimeException("not found");        // fall back 500 default

@ControllerAdvice
public class Handler {
    @ExceptionHandler(...)
    public ProblemDetail handle(...) { ... }    // serialize sai
}

@GetMapping("/orders/{id}")
public ResponseEntity<?> get(@PathVariable Long id) {
    try {
        return ResponseEntity.ok(orderService.findById(id));
    } catch (OrderNotFoundException ex) {
        return ResponseEntity.notFound().build();
    } catch (Exception ex) {
        return ResponseEntity.status(500).body(...);
    }
}

@RestControllerAdvice
public class Handler {
    @ExceptionHandler(BusinessException.class)
    public ProblemDetail handle(BusinessException ex) { ... }
    // KHONG catch Exception → unhandled → 500 default Spring
}

return ResponseEntity.ok(Map.of("error", "not found"));     // status 200 voi error body