Document that NoOpResponseErrorHandler is not a good fit with RestClient

Closes gh-33276

spring-web/src/main/java/org/springframework/web/client/NoOpResponseErrorHandler.java

@@ -17,12 +17,21 @@
 package org.springframework.web.client;
 
 import java.io.IOException;
+import java.util.function.Predicate;
 
 import org.springframework.http.client.ClientHttpResponse;
+import org.springframework.web.client.RestClient.ResponseSpec;
+import org.springframework.web.client.RestClient.ResponseSpec.ErrorHandler;
 
 /**
  * A basic, no operation {@link ResponseErrorHandler} implementation suitable
- * for ignoring any error.
+ * for ignoring any error using the {@link RestTemplate}.
+ * <p>This implementation is not suitable with the {@link RestClient} as it uses
+ * a list of candidates where the first matching is invoked. If you want to
+ * disable default status handlers with the {@code RestClient}, consider
+ * registering a noop {@link ResponseSpec.ErrorHandler ErrorHandler} with a
+ * predicate that matches all status code, see
+ * {@link RestClient.Builder#defaultStatusHandler(Predicate, ErrorHandler)}.
  *
  * @author Stephane Nicoll
  * @since 6.1.7

spring-web/src/main/java/org/springframework/web/client/RestClient.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2023 the original author or authors.
+ * Copyright 2002-2024 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -305,6 +305,10 @@ Builder defaultStatusHandler(Predicate<HttpStatusCode> statusPredicate,
 		 * to apply to every response. Such default handlers are applied in the
 		 * order in which they are registered, and after any others that are
 		 * registered for a specific response.
+		 * <p>The first status handler who claims that a response has an
+		 * error is invoked. If you want to disable other defaults, consider
+		 * using {@link #defaultStatusHandler(Predicate, ResponseSpec.ErrorHandler)}
+		 * with a predicate that matches all status codes.
 		 * @param errorHandler handler that typically, though not necessarily,
 		 * throws an exception
 		 * @return this builder