Spring Boot Exception Handling — The Production Playbook

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(OrderNotFoundException.class)  // Most specific — wins for OrderNotFoundException
    public ResponseEntity<ApiError> handleOrderNotFound(OrderNotFoundException ex) { ... }

    @ExceptionHandler(ResourceNotFoundException.class)  // Wins for ProductNotFoundException, UserNotFoundException
    public ResponseEntity<ApiError> handleNotFound(ResourceNotFoundException ex) { ... }

    @ExceptionHandler(BusinessException.class)  // Wins for PaymentDeclinedException, RateLimitExceededException
    public ResponseEntity<ApiError> handleBusiness(BusinessException ex) { ... }

    @ExceptionHandler(Exception.class)  // Catch-all — NEVER leak stack traces here
    public ResponseEntity<ApiError> handleUnexpected(Exception ex) { ... }
}

// Only controllers in these packages
@RestControllerAdvice(basePackages = "com.myshop.orders")
public class OrderExceptionHandler { ... }

// Only these specific controller classes
@RestControllerAdvice(assignableTypes = {OrderController.class, PaymentController.class})
public class PaymentExceptionHandler { ... }

// Only controllers annotated with @AdminApi
@RestControllerAdvice(annotations = AdminApi.class)
public class AdminExceptionHandler { ... }

@RestControllerAdvice(basePackages = "com.myshop.payments")
@Order(1)  // Highest priority — handles payment-specific exceptions first
public class PaymentExceptionHandler { ... }

@RestControllerAdvice
@Order(Ordered.LOWEST_PRECEDENCE)  // Catch-all — handles everything else
public class GlobalExceptionHandler { ... }

@RestControllerAdvice
@Slf4j
@Order(Ordered.LOWEST_PRECEDENCE)
public class GlobalExceptionHandler extends ResponseEntityExceptionHandler {

    // ═══════════════════════════════════════════════════════════════
    // 404 — Resource Not Found
    // ═══════════════════════════════════════════════════════════════
    @ExceptionHandler(ResourceNotFoundException.class)
    public ResponseEntity<ApiError> handleNotFound(
            ResourceNotFoundException ex, HttpServletRequest request) {

        String traceId = MDC.get("traceId");
        log.warn("[{}] Resource not found: {} | path={}", 
                 traceId, ex.getMessage(), request.getRequestURI());

        ApiError error = ApiError.builder()
            .status(404)
            .error("Not Found")
            .errorCode(ex.getErrorCode())
            .message(ex.getMessage())
            .path(request.getRequestURI())
            .traceId(traceId)
            .build();

        return ResponseEntity.status(404).body(error);
    }

    // ═══════════════════════════════════════════════════════════════
    // 409 — Conflict (optimistic locking, inventory, duplicate)
    // ═══════════════════════════════════════════════════════════════
    @ExceptionHandler(ConflictException.class)
    public ResponseEntity<ApiError> handleConflict(
            ConflictException ex, HttpServletRequest request) {

        String traceId = MDC.get("traceId");
        log.warn("[{}] Conflict: code={}, message={} | path={}",
                 traceId, ex.getErrorCode(), ex.getMessage(), request.getRequestURI());

        ApiError error = ApiError.builder()
            .status(409)
            .error("Conflict")
            .errorCode(ex.getErrorCode())
            .message(ex.getMessage())
            .path(request.getRequestURI())
            .traceId(traceId)
            .build();

        return ResponseEntity.status(409).body(error);
    }

    // ═══════════════════════════════════════════════════════════════
    // 422 — Business rule violation
    // ═══════════════════════════════════════════════════════════════
    @ExceptionHandler(BusinessException.class)
    public ResponseEntity<ApiError> handleBusinessError(
            BusinessException ex, HttpServletRequest request) {

        String traceId = MDC.get("traceId");
        log.warn("[{}] Business error: code={}, message={} | path={} | method={}",
                 traceId, ex.getErrorCode(), ex.getMessage(),
                 request.getRequestURI(), request.getMethod());

        HttpStatus status = ex.getHttpStatus();
        ApiError error = ApiError.builder()
            .status(status.value())
            .error(status.getReasonPhrase())
            .errorCode(ex.getErrorCode())
            .message(ex.getMessage())
            .path(request.getRequestURI())
            .traceId(traceId)
            .build();

        HttpHeaders headers = new HttpHeaders();
        if (ex instanceof RateLimitExceededException rle) {
            headers.add("Retry-After", String.valueOf(rle.getRetryAfterSeconds()));
        }

        return ResponseEntity.status(status).headers(headers).body(error);
    }

    // ═══════════════════════════════════════════════════════════════
    // 400 — Validation errors (@Valid / @Validated)
    // ═══════════════════════════════════════════════════════════════
    @Override
    protected ResponseEntity<Object> handleMethodArgumentNotValid(
            MethodArgumentNotValidException ex,
            HttpHeaders headers, HttpStatusCode status, WebRequest request) {

        String traceId = MDC.get("traceId");
        String path = ((ServletWebRequest) request).getRequest().getRequestURI();

        List<ApiError.FieldError> fieldErrors = ex.getBindingResult()
            .getFieldErrors().stream()
            .map(fe -> new ApiError.FieldError(
                fe.getField(), fe.getDefaultMessage(), fe.getRejectedValue()))
            .toList();

        log.warn("[{}] Validation failed: {} field errors | path={}",
                 traceId, fieldErrors.size(), path);

        ApiError error = ApiError.builder()
            .status(400)
            .error("Bad Request")
            .errorCode("VALIDATION_FAILED")
            .message("Request validation failed")
            .path(path)
            .traceId(traceId)
            .fieldErrors(fieldErrors)
            .build();

        return ResponseEntity.badRequest().body(error);
    }

    // ═══════════════════════════════════════════════════════════════
    // 400 — Constraint violations (path variables, request params)
    // ═══════════════════════════════════════════════════════════════
    @ExceptionHandler(ConstraintViolationException.class)
    public ResponseEntity<ApiError> handleConstraintViolation(
            ConstraintViolationException ex, HttpServletRequest request) {

        String traceId = MDC.get("traceId");

        List<ApiError.FieldError> fieldErrors = ex.getConstraintViolations().stream()
            .map(cv -> {
                String field = StreamSupport.stream(
                    cv.getPropertyPath().spliterator(), false)
                    .reduce((a, b) -> b)
                    .map(Object::toString)
                    .orElse("unknown");
                return new ApiError.FieldError(field, cv.getMessage(), cv.getInvalidValue());
            })
            .toList();

        log.warn("[{}] Constraint violation: {} violations | path={}",
                 traceId, fieldErrors.size(), request.getRequestURI());

        ApiError error = ApiError.builder()
            .status(400)
            .error("Bad Request")
            .errorCode("CONSTRAINT_VIOLATION")
            .message("Request parameter validation failed")
            .path(request.getRequestURI())
            .traceId(traceId)
            .fieldErrors(fieldErrors)
            .build();

        return ResponseEntity.badRequest().body(error);
    }

    // ═══════════════════════════════════════════════════════════════
    // 401 — Authentication required
    // ═══════════════════════════════════════════════════════════════
    @ExceptionHandler(AuthenticationException.class)
    public ResponseEntity<ApiError> handleAuthentication(
            AuthenticationException ex, HttpServletRequest request) {

        String traceId = MDC.get("traceId");
        log.warn("[{}] Authentication failed | path={} | method={}",
                 traceId, request.getRequestURI(), request.getMethod());

        ApiError error = ApiError.builder()
            .status(401)
            .error("Unauthorized")
            .errorCode("AUTHENTICATION_REQUIRED")
            .message("Authentication is required to access this resource")
            .path(request.getRequestURI())
            .traceId(traceId)
            .build();

        return ResponseEntity.status(401).body(error);
    }

    // ═══════════════════════════════════════════════════════════════
    // 403 — Access denied
    // ═══════════════════════════════════════════════════════════════
    @ExceptionHandler(AccessDeniedException.class)
    public ResponseEntity<ApiError> handleAccessDenied(
            AccessDeniedException ex, HttpServletRequest request) {

        String traceId = MDC.get("traceId");
        log.warn("[{}] Access denied | path={} | method={} | user={}",
                 traceId, request.getRequestURI(), request.getMethod(),
                 request.getUserPrincipal() != null ? 
                     request.getUserPrincipal().getName() : "anonymous");

        ApiError error = ApiError.builder()
            .status(403)
            .error("Forbidden")
            .errorCode("ACCESS_DENIED")
            .message("You do not have permission to access this resource")
            .path(request.getRequestURI())
            .traceId(traceId)
            .build();

        return ResponseEntity.status(403).body(error);
    }

    // ═══════════════════════════════════════════════════════════════
    // 5xx — Technical exceptions (downstream failures)
    // ═══════════════════════════════════════════════════════════════
    @ExceptionHandler(TechnicalException.class)
    public ResponseEntity<ApiError> handleTechnicalError(
            TechnicalException ex, HttpServletRequest request) {

        String traceId = MDC.get("traceId");
        log.error("[{}] Technical error: code={} | path={} | method={}",
                  traceId, ex.getErrorCode(), request.getRequestURI(),
                  request.getMethod(), ex);  // Full stack trace for 5xx

        HttpStatus status = ex.getHttpStatus();
        ApiError error = ApiError.builder()
            .status(status.value())
            .error(status.getReasonPhrase())
            .errorCode(ex.getErrorCode())
            .message("A downstream service error occurred. Please retry.")
            .path(request.getRequestURI())
            .traceId(traceId)
            .build();

        return ResponseEntity.status(status).body(error);
    }

    // ═══════════════════════════════════════════════════════════════
    // 500 — Catch-all (NEVER leak internals)
    // ═══════════════════════════════════════════════════════════════
    @ExceptionHandler(Exception.class)
    public ResponseEntity<ApiError> handleUnexpected(
            Exception ex, HttpServletRequest request) {

        String traceId = MDC.get("traceId");
        log.error("[{}] Unexpected error | path={} | method={} | query={}",
                  traceId, request.getRequestURI(), request.getMethod(),
                  request.getQueryString(), ex);  // FULL stack trace in logs

        ApiError error = ApiError.builder()
            .status(500)
            .error("Internal Server Error")
            .errorCode("INTERNAL_ERROR")
            .message("An unexpected error occurred. Please contact support with traceId: " + traceId)
            .path(request.getRequestURI())
            .traceId(traceId)
            .build();

        return ResponseEntity.status(500).body(error);
    }
}

@Builder
public record ApiError(
    int status,
    String error,
    String errorCode,
    String message,
    String path,
    String traceId,
    @Builder.Default Instant timestamp = Instant.now(),
    @JsonInclude(JsonInclude.Include.NON_NULL) List<FieldError> fieldErrors
) {
    public record FieldError(String field, String message, Object rejectedValue) {}
}

@RestControllerAdvice
public class ProblemDetailExceptionHandler extends ResponseEntityExceptionHandler {

    @ExceptionHandler(OrderNotFoundException.class)
    public ProblemDetail handleOrderNotFound(OrderNotFoundException ex,
                                             HttpServletRequest request) {
        ProblemDetail problem = ProblemDetail.forStatusAndDetail(
            HttpStatus.NOT_FOUND, ex.getMessage());

        problem.setTitle("Order Not Found");
        problem.setType(URI.create("https://api.myshop.com/errors/order-not-found"));
        problem.setInstance(URI.create(request.getRequestURI()));

        // Extension properties — anything you need
        problem.setProperty("errorCode", ex.getErrorCode());
        problem.setProperty("traceId", MDC.get("traceId"));
        problem.setProperty("timestamp", Instant.now());
        problem.setProperty("resourceType", ex.getResourceType());

        return problem;
    }

    @ExceptionHandler(PaymentDeclinedException.class)
    public ProblemDetail handlePaymentDeclined(PaymentDeclinedException ex,
                                               HttpServletRequest request) {
        ProblemDetail problem = ProblemDetail.forStatusAndDetail(
            HttpStatus.UNPROCESSABLE_ENTITY, ex.getMessage());

        problem.setTitle("Payment Declined");
        problem.setType(URI.create("https://api.myshop.com/errors/payment-declined"));
        problem.setInstance(URI.create(request.getRequestURI()));
        problem.setProperty("errorCode", ex.getErrorCode());
        problem.setProperty("declineReason", ex.getDeclineReason());
        problem.setProperty("traceId", MDC.get("traceId"));

        return problem;
    }
}

public record CreateOrderRequest(
    @NotBlank(message = "Customer ID is required")
    String customerId,

    @NotEmpty(message = "At least one item is required")
    List<@Valid OrderItemRequest> items,  // @Valid triggers nested validation

    @Positive(message = "Amount must be positive")
    BigDecimal amount,

    @Email(message = "Must be a valid email")
    String contactEmail,

    @Valid  // Nested object validation
    @NotNull(message = "Shipping address is required")
    AddressRequest shippingAddress
) {}

public record OrderItemRequest(
    @NotBlank(message = "SKU is required")
    String sku,

    @Min(value = 1, message = "Quantity must be at least 1")
    @Max(value = 100, message = "Quantity cannot exceed 100")
    int quantity
) {}

public record AddressRequest(
    @NotBlank(message = "Street is required") String street,
    @NotBlank(message = "City is required") String city,
    @NotBlank(message = "Zip code is required") String zipCode,
    @Size(min = 2, max = 2, message = "Country code must be 2 characters") String countryCode
) {}

@PostMapping("/orders")
public ResponseEntity<Order> createOrder(@Valid @RequestBody CreateOrderRequest request) {
    // If we get here, validation passed. No try-catch needed.
    Order order = orderService.create(request);
    return ResponseEntity.status(201).body(order);
}

@RestController
@RequestMapping("/api/orders")
@Validated  // Required at class level for method parameter validation
public class OrderController {

    @GetMapping("/{id}")
    public Order getOrder(@PathVariable @Min(1) Long id) { ... }

    @GetMapping
    public Page<Order> listOrders(
            @RequestParam @Min(0) int page,
            @RequestParam @Min(1) @Max(100) int size) { ... }
}

@RestController
@RequestMapping("/api/orders")
public class OrderController {

    @PostMapping
    public ResponseEntity<OrderResponse> createOrder(@Valid @RequestBody CreateOrderRequest request) {
        // Clean controller — no try-catch. Exceptions propagate to global handler.
        OrderResponse response = orderService.createOrder(request);
        return ResponseEntity.status(HttpStatus.CREATED).body(response);
    }
}

@Service
@Transactional
public class OrderService {

    public OrderResponse createOrder(CreateOrderRequest request) {
        // Throw specific, meaningful exceptions
        Customer customer = customerRepository.findById(request.customerId())
            .orElseThrow(() -> new ResourceNotFoundException("Customer", "id", request.customerId()));

        for (OrderItemRequest item : request.items()) {
            int available = inventoryService.getAvailable(item.sku());
            if (available < item.quantity()) {
                throw new InsufficientInventoryException(item.sku(), item.quantity(), available);
            }
        }

        Order order = buildOrder(request);

        try {
            paymentService.charge(order);
        } catch (PaymentGatewayException ex) {
            // Translate external exception to YOUR domain exception
            throw new PaymentDeclinedException(order.getId(), ex.getDeclineCode());
        }

        return toResponse(orderRepository.save(order));
    }
}

@Repository
public class OrderRepositoryImpl {

    public Order updateWithOptimisticLock(Order order) {
        try {
            return jpaRepository.save(order);
        } catch (OptimisticLockingFailureException ex) {
            // Translate Spring's exception to YOUR domain exception
            throw new ConflictException("ORDER_CONCURRENT_MODIFICATION",
                "Order " + order.getId() + " was modified by another request");
        }
    }
}

@Component
@Order(Ordered.HIGHEST_PRECEDENCE)
public class ExceptionHandlerFilter extends OncePerRequestFilter {

    @Autowired
    @Qualifier("handlerExceptionResolver")
    private HandlerExceptionResolver resolver;

    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                    HttpServletResponse response,
                                    FilterChain chain) throws ServletException, IOException {
        try {
            chain.doFilter(request, response);
        } catch (Exception ex) {
            // Delegates to @ControllerAdvice handlers — same error format everywhere
            resolver.resolveException(request, response, null, ex);
        }
    }
}

@Component
public class CustomAuthenticationEntryPoint implements AuthenticationEntryPoint {

    private final ObjectMapper objectMapper;

    @Override
    public void commence(HttpServletRequest request, HttpServletResponse response,
                        AuthenticationException ex) throws IOException {
        response.setContentType(MediaType.APPLICATION_JSON_VALUE);
        response.setStatus(HttpStatus.UNAUTHORIZED.value());

        ApiError error = ApiError.builder()
            .status(401)
            .error("Unauthorized")
            .errorCode("AUTHENTICATION_REQUIRED")
            .message("Authentication is required")
            .path(request.getRequestURI())
            .traceId(MDC.get("traceId"))
            .build();

        objectMapper.writeValue(response.getOutputStream(), error);
    }
}

@Component
public class CustomAccessDeniedHandler implements AccessDeniedHandler {

    private final ObjectMapper objectMapper;

    @Override
    public void handle(HttpServletRequest request, HttpServletResponse response,
                      AccessDeniedException ex) throws IOException {
        response.setContentType(MediaType.APPLICATION_JSON_VALUE);
        response.setStatus(HttpStatus.FORBIDDEN.value());

        ApiError error = ApiError.builder()
            .status(403)
            .error("Forbidden")
            .errorCode("ACCESS_DENIED")
            .message("Insufficient permissions")
            .path(request.getRequestURI())
            .traceId(MDC.get("traceId"))
            .build();

        objectMapper.writeValue(response.getOutputStream(), error);
    }
}

@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
    return http
        .exceptionHandling(ex -> ex
            .authenticationEntryPoint(customAuthenticationEntryPoint)
            .accessDeniedHandler(customAccessDeniedHandler))
        .build();
}

@Component
public class TraceIdFilter extends OncePerRequestFilter {

    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                    HttpServletResponse response,
                                    FilterChain chain) throws ServletException, IOException {
        String traceId = Optional.ofNullable(request.getHeader("X-Trace-Id"))
            .orElse(UUID.randomUUID().toString());

        MDC.put("traceId", traceId);
        response.setHeader("X-Trace-Id", traceId);

        try {
            chain.doFilter(request, response);
        } finally {
            MDC.clear();
        }
    }
}

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

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

@RestControllerAdvice
public class GlobalExceptionHandler extends ResponseEntityExceptionHandler {

    @Override
    protected ResponseEntity<Object> handleHttpRequestMethodNotSupported(
            HttpRequestMethodNotSupportedException ex,
            HttpHeaders headers, HttpStatusCode status, WebRequest request) {

        String path = ((ServletWebRequest) request).getRequest().getRequestURI();
        ApiError error = ApiError.builder()
            .status(405)
            .error("Method Not Allowed")
            .errorCode("METHOD_NOT_SUPPORTED")
            .message(ex.getMethod() + " is not supported. Supported: " + ex.getSupportedHttpMethods())
            .path(path)
            .traceId(MDC.get("traceId"))
            .build();

        return ResponseEntity.status(405).body(error);
    }

    @Override
    protected ResponseEntity<Object> handleHttpMessageNotReadable(
            HttpMessageNotReadableException ex,
            HttpHeaders headers, HttpStatusCode status, WebRequest request) {

        String path = ((ServletWebRequest) request).getRequest().getRequestURI();
        ApiError error = ApiError.builder()
            .status(400)
            .error("Bad Request")
            .errorCode("MALFORMED_REQUEST")
            .message("Request body is malformed or missing")
            .path(path)
            .traceId(MDC.get("traceId"))
            .build();

        return ResponseEntity.badRequest().body(error);
    }
}

// This exception will NOT reach your @ControllerAdvice
@Async
public void processOrderAsync(Long orderId) {
    // If this throws, it's lost unless you handle it
    Order order = orderRepository.findById(orderId)
        .orElseThrow(() -> new OrderNotFoundException(orderId));
    // ...
}

@Async
public CompletableFuture<OrderResult> processOrderAsync(Long orderId) {
    Order order = orderRepository.findById(orderId)
        .orElseThrow(() -> new OrderNotFoundException(orderId));
    return CompletableFuture.completedFuture(process(order));
}

// Caller
orderService.processOrderAsync(id)
    .exceptionally(ex -> {
        log.error("Async order processing failed: {}", id, ex);
        return OrderResult.failed(ex.getMessage());
    });

@Configuration
public class AsyncConfig implements AsyncConfigurer {
    @Override
    public AsyncUncaughtExceptionHandler getAsyncUncaughtExceptionHandler() {
        return (ex, method, params) -> {
            log.error("Uncaught async exception in {}.{}: {}",
                method.getDeclaringClass().getSimpleName(),
                method.getName(), ex.getMessage(), ex);
            // Alert, metric, dead letter queue, etc.
        };
    }
}