diff --git a/spring-web/src/main/java/org/springframework/web/client/NoOpResponseErrorHandler.java b/spring-web/src/main/java/org/springframework/web/client/NoOpResponseErrorHandler.java
index 4d1498b4030..ae699f2bc5c 100644
--- a/spring-web/src/main/java/org/springframework/web/client/NoOpResponseErrorHandler.java
+++ b/spring-web/src/main/java/org/springframework/web/client/NoOpResponseErrorHandler.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2024 the original author or authors.
+ * Copyright 2002-2025 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.
@@ -25,7 +25,7 @@ import org.springframework.web.client.RestClient.ResponseSpec.ErrorHandler;
 
 /**
  * A basic, no operation {@link ResponseErrorHandler} implementation suitable
- * for ignoring any error using the {@link RestTemplate}.
+ * for ignoring any error using the {@link RestTemplate} or {@link RestClient}.
  * <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
diff --git a/spring-web/src/main/java/org/springframework/web/client/ResponseErrorHandler.java b/spring-web/src/main/java/org/springframework/web/client/ResponseErrorHandler.java
index 8d7f82f3b75..5865a166b6b 100644
--- a/spring-web/src/main/java/org/springframework/web/client/ResponseErrorHandler.java
+++ b/spring-web/src/main/java/org/springframework/web/client/ResponseErrorHandler.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2018 the original author or authors.
+ * Copyright 2002-2025 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.
@@ -23,8 +23,11 @@ import org.springframework.http.HttpMethod;
 import org.springframework.http.client.ClientHttpResponse;
 
 /**
- * Strategy interface used by the {@link RestTemplate} to determine
- * whether a particular response has an error or not.
+ * Strategy interface used by the {@link RestTemplate} and {@link RestClient} to
+ * determine whether a particular response has an error or not.
+ *
+ * <p>Note that {@code RestClient} also supports and recommends use of
+ * {@link RestClient.ResponseSpec#onStatus status handlers}.
  *
  * @author Arjen Poutsma
  * @since 3.0
diff --git a/spring-web/src/main/java/org/springframework/web/client/RestClientException.java b/spring-web/src/main/java/org/springframework/web/client/RestClientException.java
index c5d969be827..8793a048e6e 100644
--- a/spring-web/src/main/java/org/springframework/web/client/RestClientException.java
+++ b/spring-web/src/main/java/org/springframework/web/client/RestClientException.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2020 the original author or authors.
+ * Copyright 2002-2025 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.
@@ -17,15 +17,17 @@
 package org.springframework.web.client;
 
 import org.springframework.core.NestedRuntimeException;
-import org.springframework.http.client.ClientHttpResponse;
 import org.springframework.lang.Nullable;
 
 /**
- * Base class for exceptions thrown by {@link RestTemplate} in case a request
- * fails because of a server error response, as determined via
- * {@link ResponseErrorHandler#hasError(ClientHttpResponse)}, failure to decode
+ * Base class for exceptions thrown by {@link RestClient} and {@link RestTemplate}
+ * in case a request fails because of a server error response, a failure to decode
  * the response, or a low level I/O error.
  *
+ * <p>Server error responses are determined by
+ * {@link RestClient.ResponseSpec#onStatus status handlers} for {@code RestClient},
+ * and by {@link ResponseErrorHandler} for {@code RestTemplate}.
+ *
  * @author Arjen Poutsma
  * @since 3.0
  */
diff --git a/spring-web/src/main/java/org/springframework/web/client/RestTemplate.java b/spring-web/src/main/java/org/springframework/web/client/RestTemplate.java
index e9784a5e434..0929816d715 100644
--- a/spring-web/src/main/java/org/springframework/web/client/RestTemplate.java
+++ b/spring-web/src/main/java/org/springframework/web/client/RestTemplate.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2024 the original author or authors.
+ * Copyright 2002-2025 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.
@@ -179,7 +179,7 @@ public class RestTemplate extends InterceptingHttpAccessor implements RestOperat
 
 
 	/**
-	 * Create a new instance of the {@link RestTemplate} using default settings.
+	 * Create a new instance with default settings.
 	 * Default {@link HttpMessageConverter HttpMessageConverters} are initialized.
 	 */
 	public RestTemplate() {
@@ -238,7 +238,7 @@ public class RestTemplate extends InterceptingHttpAccessor implements RestOperat
 	}
 
 	/**
-	 * Create a new instance of the {@link RestTemplate} based on the given {@link ClientHttpRequestFactory}.
+	 * Create a new instance with the given {@link ClientHttpRequestFactory}.
 	 * @param requestFactory the HTTP request factory to use
 	 * @see org.springframework.http.client.SimpleClientHttpRequestFactory
 	 * @see org.springframework.http.client.HttpComponentsClientHttpRequestFactory
@@ -249,9 +249,8 @@ public class RestTemplate extends InterceptingHttpAccessor implements RestOperat
 	}
 
 	/**
-	 * Create a new instance of the {@link RestTemplate} using the given list of
-	 * {@link HttpMessageConverter} to use.
-	 * @param messageConverters the list of {@link HttpMessageConverter} to use
+	 * Create a new instance with the given message converters.
+	 * @param messageConverters the list of converters to use
 	 * @since 3.2.7
 	 */
 	public RestTemplate(List<HttpMessageConverter<?>> messageConverters) {