Design the error-handling contract for a REST API: @ControllerAdvice, ProblemDetail and what clients should see.

@RestControllerAdvice
class ApiExceptionHandler extends ResponseEntityExceptionHandler {

    @ExceptionHandler(MethodArgumentNotValidException.class)
    ProblemDetail invalid(MethodArgumentNotValidException e) {
        var p = ProblemDetail.forStatus(422);
        p.setType(URI.create("https://api.acme.com/errors/validation"));
        p.setProperty("violations", e.getFieldErrors().stream()
            .map(f -> Map.of("field", f.getField(), "message", f.getDefaultMessage()))
            .toList());
        return p;
    }

    @ExceptionHandler(OptimisticLockingFailureException.class)
    ProblemDetail conflict(OptimisticLockingFailureException e) {
        return ProblemDetail.forStatusAndDetail(HttpStatus.CONFLICT,
            "Resource was modified concurrently; refetch and retry.");
    }

    @ExceptionHandler(Exception.class)
    ProblemDetail unknown(Exception e, HttpServletRequest req) {
        log.error("unhandled [{}]", MDC.get("cid"), e);      // logged ONCE, full stack
        var p = ProblemDetail.forStatus(500);
        p.setProperty("correlationId", MDC.get("cid"));      // client can quote it
        return p;                                            // no internals leaked
    }
}