Add javadocs about expected exceptions to RestHighLevelClient (#36216)

Add a more detailed section about what exceptions to expect from the blocking
calls in this class and removing the mostly redundant mentions of the
IOExceptions from each method javadoc since it doesn't give much details about
the expected exceptions anyway.

Closes #30334

client/rest-high-level/src/main/java/org/elasticsearch/client/RestHighLevelClient.java

@@ -58,10 +58,10 @@ import org.elasticsearch.action.update.UpdateRequest;
 import org.elasticsearch.action.update.UpdateResponse;
 import org.elasticsearch.client.core.CountRequest;
 import org.elasticsearch.client.core.CountResponse;
-import org.elasticsearch.client.core.TermVectorsResponse;
-import org.elasticsearch.client.core.TermVectorsRequest;
 import org.elasticsearch.client.core.MultiTermVectorsRequest;
 import org.elasticsearch.client.core.MultiTermVectorsResponse;
+import org.elasticsearch.client.core.TermVectorsRequest;
+import org.elasticsearch.client.core.TermVectorsResponse;
 import org.elasticsearch.client.tasks.TaskSubmissionResponse;
 import org.elasticsearch.common.CheckedConsumer;
 import org.elasticsearch.common.CheckedFunction;
@@ -139,6 +139,7 @@ import org.elasticsearch.search.aggregations.metrics.InternalHDRPercentiles;
 import org.elasticsearch.search.aggregations.metrics.InternalTDigestPercentileRanks;
 import org.elasticsearch.search.aggregations.metrics.InternalTDigestPercentiles;
 import org.elasticsearch.search.aggregations.metrics.MaxAggregationBuilder;
+import org.elasticsearch.search.aggregations.metrics.MedianAbsoluteDeviationAggregationBuilder;
 import org.elasticsearch.search.aggregations.metrics.MinAggregationBuilder;
 import org.elasticsearch.search.aggregations.metrics.ParsedAvg;
 import org.elasticsearch.search.aggregations.metrics.ParsedCardinality;
@@ -148,6 +149,7 @@ import org.elasticsearch.search.aggregations.metrics.ParsedGeoCentroid;
 import org.elasticsearch.search.aggregations.metrics.ParsedHDRPercentileRanks;
 import org.elasticsearch.search.aggregations.metrics.ParsedHDRPercentiles;
 import org.elasticsearch.search.aggregations.metrics.ParsedMax;
+import org.elasticsearch.search.aggregations.metrics.ParsedMedianAbsoluteDeviation;
 import org.elasticsearch.search.aggregations.metrics.ParsedMin;
 import org.elasticsearch.search.aggregations.metrics.ParsedScriptedMetric;
 import org.elasticsearch.search.aggregations.metrics.ParsedStats;
@@ -161,20 +163,18 @@ import org.elasticsearch.search.aggregations.metrics.StatsAggregationBuilder;
 import org.elasticsearch.search.aggregations.metrics.SumAggregationBuilder;
 import org.elasticsearch.search.aggregations.metrics.TopHitsAggregationBuilder;
 import org.elasticsearch.search.aggregations.metrics.ValueCountAggregationBuilder;
-import org.elasticsearch.search.aggregations.metrics.MedianAbsoluteDeviationAggregationBuilder;
-import org.elasticsearch.search.aggregations.metrics.ParsedMedianAbsoluteDeviation;
-import org.elasticsearch.search.aggregations.pipeline.InternalSimpleValue;
-import org.elasticsearch.search.aggregations.pipeline.ParsedSimpleValue;
+import org.elasticsearch.search.aggregations.pipeline.DerivativePipelineAggregationBuilder;
+import org.elasticsearch.search.aggregations.pipeline.ExtendedStatsBucketPipelineAggregationBuilder;
 import org.elasticsearch.search.aggregations.pipeline.InternalBucketMetricValue;
+import org.elasticsearch.search.aggregations.pipeline.InternalSimpleValue;
 import org.elasticsearch.search.aggregations.pipeline.ParsedBucketMetricValue;
+import org.elasticsearch.search.aggregations.pipeline.ParsedDerivative;
+import org.elasticsearch.search.aggregations.pipeline.ParsedExtendedStatsBucket;
 import org.elasticsearch.search.aggregations.pipeline.ParsedPercentilesBucket;
-import org.elasticsearch.search.aggregations.pipeline.PercentilesBucketPipelineAggregationBuilder;
+import org.elasticsearch.search.aggregations.pipeline.ParsedSimpleValue;
 import org.elasticsearch.search.aggregations.pipeline.ParsedStatsBucket;
+import org.elasticsearch.search.aggregations.pipeline.PercentilesBucketPipelineAggregationBuilder;
 import org.elasticsearch.search.aggregations.pipeline.StatsBucketPipelineAggregationBuilder;
-import org.elasticsearch.search.aggregations.pipeline.ExtendedStatsBucketPipelineAggregationBuilder;
-import org.elasticsearch.search.aggregations.pipeline.ParsedExtendedStatsBucket;
-import org.elasticsearch.search.aggregations.pipeline.DerivativePipelineAggregationBuilder;
-import org.elasticsearch.search.aggregations.pipeline.ParsedDerivative;
 import org.elasticsearch.search.suggest.Suggest;
 import org.elasticsearch.search.suggest.completion.CompletionSuggestion;
 import org.elasticsearch.search.suggest.completion.CompletionSuggestionBuilder;
@@ -203,13 +203,33 @@ import static java.util.Collections.singleton;
 import static java.util.stream.Collectors.toList;
 
 /**
- * High level REST client that wraps an instance of the low level {@link RestClient} and allows to build requests and read responses.
- * The {@link RestClient} instance is internally built based on the provided {@link RestClientBuilder} and it gets closed automatically
- * when closing the {@link RestHighLevelClient} instance that wraps it.
+ * High level REST client that wraps an instance of the low level {@link RestClient} and allows to build requests and read responses. The
+ * {@link RestClient} instance is internally built based on the provided {@link RestClientBuilder} and it gets closed automatically when
+ * closing the {@link RestHighLevelClient} instance that wraps it.
+ * <p>
+ *
  * In case an already existing instance of a low-level REST client needs to be provided, this class can be subclassed and the
- * {@link #RestHighLevelClient(RestClient, CheckedConsumer, List)}  constructor can be used.
- * This class can also be sub-classed to expose additional client methods that make use of endpoints added to Elasticsearch through
- * plugins, or to add support for custom response sections, again added to Elasticsearch through plugins.
+ * {@link #RestHighLevelClient(RestClient, CheckedConsumer, List)} constructor can be used.
+ * <p>
+ *
+ * This class can also be sub-classed to expose additional client methods that make use of endpoints added to Elasticsearch through plugins,
+ * or to add support for custom response sections, again added to Elasticsearch through plugins.
+ * <p>
+ *
+ * The majority of the methods in this class come in two flavors, a blocking and an asynchronous version (e.g.
+ * {@link #search(SearchRequest, RequestOptions)} and {@link #searchAsync(SearchRequest, RequestOptions, ActionListener)}, where the later
+ * takes an implementation of an {@link ActionListener} as an argument that needs to implement methods that handle successful responses and
+ * failure scenarios. Most of the blocking calls can throw an {@link IOException} or an unchecked {@link ElasticsearchException} in the
+ * following cases:
+ *
+ * <ul>
+ * <li>an {@link IOException} is usually thrown in case of failing to parse the REST response in the high-level REST client, the request
+ * times out or similar cases where there is no response coming back from the Elasticsearch server</li>
+ * <li>an {@link ElasticsearchException} is usually thrown in case where the server returns a 4xx or 5xx error code. The high-level client
+ * then tries to parse the response body error details into a generic ElasticsearchException and suppresses the original
+ * {@link ResponseException}</li>
+ * </ul>
+ *
  */
 public class RestHighLevelClient implements Closeable {
 
@@ -448,7 +468,6 @@ public class RestHighLevelClient implements Closeable {
      * @param bulkRequest the request
      * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
      * @return the response
-     * @throws IOException in case there is a problem sending the request or parsing back the response
      */
     public final BulkResponse bulk(BulkRequest bulkRequest, RequestOptions options) throws IOException {
         return performRequestAndParseEntity(bulkRequest, RequestConverters::bulk, options, BulkResponse::fromXContent, emptySet());
@@ -471,7 +490,6 @@ public class RestHighLevelClient implements Closeable {
      * @param reindexRequest the request
      * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
      * @return the response
-     * @throws IOException in case there is a problem sending the request or parsing back the response
      */
     public final BulkByScrollResponse reindex(ReindexRequest reindexRequest, RequestOptions options) throws IOException {
         return performRequestAndParseEntity(
@@ -485,7 +503,6 @@ public class RestHighLevelClient implements Closeable {
      * @param reindexRequest the request
      * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
      * @return the submission response
-     * @throws IOException in case there is a problem sending the request or parsing back the response
      */
     public final TaskSubmissionResponse submitReindexTask(ReindexRequest reindexRequest, RequestOptions options) throws IOException {
         return performRequestAndParseEntity(
@@ -513,7 +530,6 @@ public class RestHighLevelClient implements Closeable {
      * @param updateByQueryRequest the request
      * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
      * @return the response
-     * @throws IOException in case there is a problem sending the request or parsing back the response
      */
     public final BulkByScrollResponse updateByQuery(UpdateByQueryRequest updateByQueryRequest, RequestOptions options) throws IOException {
         return performRequestAndParseEntity(
@@ -543,7 +559,6 @@ public class RestHighLevelClient implements Closeable {
      * @param deleteByQueryRequest the request
      * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
      * @return the response
-     * @throws IOException in case there is a problem sending the request or parsing back the response
      */
     public final BulkByScrollResponse deleteByQuery(DeleteByQueryRequest deleteByQueryRequest, RequestOptions options) throws IOException {
         return performRequestAndParseEntity(
@@ -573,7 +588,6 @@ public class RestHighLevelClient implements Closeable {
      * @param rethrottleRequest the request
      * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
      * @return the response
-     * @throws IOException in case there is a problem sending the request or parsing back the response
      */
     public final ListTasksResponse deleteByQueryRethrottle(RethrottleRequest rethrottleRequest, RequestOptions options) throws IOException {
         return performRequestAndParseEntity(rethrottleRequest, RequestConverters::rethrottleDeleteByQuery, options,
@@ -601,7 +615,6 @@ public class RestHighLevelClient implements Closeable {
      * @param rethrottleRequest the request
      * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
      * @return the response
-     * @throws IOException in case there is a problem sending the request or parsing back the response
      */
     public final ListTasksResponse updateByQueryRethrottle(RethrottleRequest rethrottleRequest, RequestOptions options) throws IOException {
         return performRequestAndParseEntity(rethrottleRequest, RequestConverters::rethrottleUpdateByQuery, options,
@@ -630,7 +643,6 @@ public class RestHighLevelClient implements Closeable {
      * @param rethrottleRequest the request
      * @param options           the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
      * @return the response
-     * @throws IOException in case there is a problem sending the request or parsing back the response
      */
     public final ListTasksResponse reindexRethrottle(RethrottleRequest rethrottleRequest, RequestOptions options) throws IOException {
         return performRequestAndParseEntity(rethrottleRequest, RequestConverters::rethrottleReindex, options,
@@ -656,7 +668,6 @@ public class RestHighLevelClient implements Closeable {
      * Pings the remote Elasticsearch cluster and returns true if the ping succeeded, false otherwise
      * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
      * @return <code>true</code> if the ping succeeded, false otherwise
-     * @throws IOException in case there is a problem sending the request
      */
     public final boolean ping(RequestOptions options) throws IOException {
         return performRequest(new MainRequest(), (request) -> RequestConverters.ping(), options, RestHighLevelClient::convertExistsResponse,
@@ -667,7 +678,6 @@ public class RestHighLevelClient implements Closeable {
      * Get the cluster info otherwise provided when sending an HTTP request to '/'
      * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
      * @return the response
-     * @throws IOException in case there is a problem sending the request or parsing back the response
      */
     public final MainResponse info(RequestOptions options) throws IOException {
         return performRequestAndParseEntity(new MainRequest(), (request) -> RequestConverters.info(), options,
@@ -680,7 +690,6 @@ public class RestHighLevelClient implements Closeable {
      * @param getRequest the request
      * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
      * @return the response
-     * @throws IOException in case there is a problem sending the request or parsing back the response
      */
     public final GetResponse get(GetRequest getRequest, RequestOptions options) throws IOException {
         return performRequestAndParseEntity(getRequest, RequestConverters::get, options, GetResponse::fromXContent, singleton(404));
@@ -704,7 +713,6 @@ public class RestHighLevelClient implements Closeable {
      * @param multiGetRequest the request
      * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
      * @return the response
-     * @throws IOException in case there is a problem sending the request or parsing back the response
      * @deprecated use {@link #mget(MultiGetRequest, RequestOptions)} instead
      */
     @Deprecated
@@ -719,7 +727,6 @@ public class RestHighLevelClient implements Closeable {
      * @param multiGetRequest the request
      * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
      * @return the response
-     * @throws IOException in case there is a problem sending the request or parsing back the response
      */
     public final MultiGetResponse mget(MultiGetRequest multiGetRequest, RequestOptions options) throws IOException {
         return performRequestAndParseEntity(multiGetRequest, RequestConverters::multiGet, options, MultiGetResponse::fromXContent,
@@ -757,7 +764,6 @@ public class RestHighLevelClient implements Closeable {
      * @param getRequest the request
      * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
      * @return <code>true</code> if the document exists, <code>false</code> otherwise
-     * @throws IOException in case there is a problem sending the request
      */
     public final boolean exists(GetRequest getRequest, RequestOptions options) throws IOException {
         return performRequest(getRequest, RequestConverters::exists, options, RestHighLevelClient::convertExistsResponse, emptySet());
@@ -777,20 +783,19 @@ public class RestHighLevelClient implements Closeable {
 
     /**
      * Checks for the existence of a document with a "_source" field. Returns true if it exists, false otherwise.
-     * See <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-get.html#_source">Source exists API 
+     * See <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-get.html#_source">Source exists API
      * on elastic.co</a>
      * @param getRequest the request
      * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
      * @return <code>true</code> if the document and _source field exists, <code>false</code> otherwise
-     * @throws IOException in case there is a problem sending the request
      */
     public boolean existsSource(GetRequest getRequest, RequestOptions options) throws IOException {
         return performRequest(getRequest, RequestConverters::sourceExists, options, RestHighLevelClient::convertExistsResponse, emptySet());
-    }     
-    
+    }
+
     /**
      * Asynchronously checks for the existence of a document with a "_source" field. Returns true if it exists, false otherwise.
-     * See <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-get.html#_source">Source exists API 
+     * See <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-get.html#_source">Source exists API
      * on elastic.co</a>
      * @param getRequest the request
      * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
@@ -799,15 +804,14 @@ public class RestHighLevelClient implements Closeable {
     public final void existsSourceAsync(GetRequest getRequest, RequestOptions options, ActionListener<Boolean> listener) {
         performRequestAsync(getRequest, RequestConverters::sourceExists, options, RestHighLevelClient::convertExistsResponse, listener,
                 emptySet());
-    }    
-    
+    }
+
     /**
      * Index a document using the Index API.
      * See <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-index_.html">Index API on elastic.co</a>
      * @param indexRequest the request
      * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
      * @return the response
-     * @throws IOException in case there is a problem sending the request or parsing back the response
      */
     public final IndexResponse index(IndexRequest indexRequest, RequestOptions options) throws IOException {
         return performRequestAndParseEntity(indexRequest, RequestConverters::index, options, IndexResponse::fromXContent, emptySet());
@@ -831,7 +835,6 @@ public class RestHighLevelClient implements Closeable {
      * @param countRequest the request
      * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
      * @return the response
-     * @throws IOException in case there is a problem sending the request or parsing back the response
      */
     public final CountResponse count(CountRequest countRequest, RequestOptions options) throws IOException {
         return performRequestAndParseEntity(countRequest, RequestConverters::count, options, CountResponse::fromXContent,
@@ -856,7 +859,6 @@ public class RestHighLevelClient implements Closeable {
      * @param updateRequest the request
      * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
      * @return the response
-     * @throws IOException in case there is a problem sending the request or parsing back the response
      */
     public final UpdateResponse update(UpdateRequest updateRequest, RequestOptions options) throws IOException {
         return performRequestAndParseEntity(updateRequest, RequestConverters::update, options, UpdateResponse::fromXContent, emptySet());
@@ -877,10 +879,9 @@ public class RestHighLevelClient implements Closeable {
     /**
      * Deletes a document by id using the Delete API.
      * See <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-delete.html">Delete API on elastic.co</a>
-     * @param deleteRequest the reuqest
+     * @param deleteRequest the request
      * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
      * @return the response
-     * @throws IOException in case there is a problem sending the request or parsing back the response
      */
     public final DeleteResponse delete(DeleteRequest deleteRequest, RequestOptions options) throws IOException {
         return performRequestAndParseEntity(deleteRequest, RequestConverters::delete, options, DeleteResponse::fromXContent,
@@ -905,7 +906,6 @@ public class RestHighLevelClient implements Closeable {
      * @param searchRequest the request
      * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
      * @return the response
-     * @throws IOException in case there is a problem sending the request or parsing back the response
      */
     public final SearchResponse search(SearchRequest searchRequest, RequestOptions options) throws IOException {
         return performRequestAndParseEntity(searchRequest, RequestConverters::search, options, SearchResponse::fromXContent, emptySet());
@@ -930,7 +930,6 @@ public class RestHighLevelClient implements Closeable {
      * @param multiSearchRequest the request
      * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
      * @return the response
-     * @throws IOException in case there is a problem sending the request or parsing back the response
      * @deprecated use {@link #msearch(MultiSearchRequest, RequestOptions)} instead
      */
     @Deprecated
@@ -945,7 +944,6 @@ public class RestHighLevelClient implements Closeable {
      * @param multiSearchRequest the request
      * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
      * @return the response
-     * @throws IOException in case there is a problem sending the request or parsing back the response
      */
     public final MultiSearchResponse msearch(MultiSearchRequest multiSearchRequest, RequestOptions options) throws IOException {
         return performRequestAndParseEntity(multiSearchRequest, RequestConverters::multiSearch, options, MultiSearchResponse::fromXContext,
@@ -988,7 +986,6 @@ public class RestHighLevelClient implements Closeable {
      * @param searchScrollRequest the request
      * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
      * @return the response
-     * @throws IOException in case there is a problem sending the request or parsing back the response
      * @deprecated use {@link #scroll(SearchScrollRequest, RequestOptions)} instead
      */
     @Deprecated
@@ -1003,7 +1000,6 @@ public class RestHighLevelClient implements Closeable {
      * @param searchScrollRequest the request
      * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
      * @return the response
-     * @throws IOException in case there is a problem sending the request or parsing back the response
      */
     public final SearchResponse scroll(SearchScrollRequest searchScrollRequest, RequestOptions options) throws IOException {
         return performRequestAndParseEntity(searchScrollRequest, RequestConverters::searchScroll, options, SearchResponse::fromXContent,
@@ -1046,7 +1042,6 @@ public class RestHighLevelClient implements Closeable {
      * @param clearScrollRequest the request
      * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
      * @return the response
-     * @throws IOException in case there is a problem sending the request or parsing back the response
      */
     public final ClearScrollResponse clearScroll(ClearScrollRequest clearScrollRequest, RequestOptions options) throws IOException {
         return performRequestAndParseEntity(clearScrollRequest, RequestConverters::clearScroll, options, ClearScrollResponse::fromXContent,
@@ -1057,7 +1052,7 @@ public class RestHighLevelClient implements Closeable {
      * Asynchronously clears one or more scroll ids using the Clear Scroll API.
      * See <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-scroll.html#_clear_scroll_api">
      * Clear Scroll API on elastic.co</a>
-     * @param clearScrollRequest the reuqest
+     * @param clearScrollRequest the request
      * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
      * @param listener the listener to be notified upon request completion
      */
@@ -1074,7 +1069,6 @@ public class RestHighLevelClient implements Closeable {
      * @param searchTemplateRequest the request
      * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
      * @return the response
-     * @throws IOException in case there is a problem sending the request or parsing back the response
      */
     public final SearchTemplateResponse searchTemplate(SearchTemplateRequest searchTemplateRequest,
                                                        RequestOptions options) throws IOException {
@@ -1100,7 +1094,6 @@ public class RestHighLevelClient implements Closeable {
      * @param explainRequest the request
      * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
      * @return the response
-     * @throws IOException in case there is a problem sending the request or parsing back the response
      */
     public final ExplainResponse explain(ExplainRequest explainRequest, RequestOptions options) throws IOException {
         return performRequest(explainRequest, RequestConverters::explain, options,
@@ -1198,7 +1191,6 @@ public class RestHighLevelClient implements Closeable {
      * @param rankEvalRequest the request
      * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
      * @return the response
-     * @throws IOException in case there is a problem sending the request or parsing back the response
      */
     public final RankEvalResponse rankEval(RankEvalRequest rankEvalRequest, RequestOptions options) throws IOException {
         return performRequestAndParseEntity(rankEvalRequest, RequestConverters::rankEval, options, RankEvalResponse::fromXContent,
@@ -1251,7 +1243,6 @@ public class RestHighLevelClient implements Closeable {
      * @param fieldCapabilitiesRequest the request
      * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
      * @return the response
-     * @throws IOException in case there is a problem sending the request or parsing back the response
      */
     public final FieldCapabilitiesResponse fieldCaps(FieldCapabilitiesRequest fieldCapabilitiesRequest,
                                                      RequestOptions options) throws IOException {
@@ -1266,7 +1257,6 @@ public class RestHighLevelClient implements Closeable {
      * @param request the request
      * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
      * @return the response
-     * @throws IOException in case there is a problem sending the request or parsing back the response
      */
     public GetStoredScriptResponse getScript(GetStoredScriptRequest request, RequestOptions options) throws IOException {
         return performRequestAndParseEntity(request, RequestConverters::getScript, options,
@@ -1294,7 +1284,6 @@ public class RestHighLevelClient implements Closeable {
      * @param request the request
      * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
      * @return the response
-     * @throws IOException in case there is a problem sending the request or parsing back the response
      */
     public AcknowledgedResponse deleteScript(DeleteStoredScriptRequest request, RequestOptions options) throws IOException {
         return performRequestAndParseEntity(request, RequestConverters::deleteScript, options,
@@ -1322,7 +1311,6 @@ public class RestHighLevelClient implements Closeable {
      * @param putStoredScriptRequest the request
      * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
      * @return the response
-     * @throws IOException in case there is a problem sending the request or parsing back the response
      */
     public AcknowledgedResponse putScript(PutStoredScriptRequest putStoredScriptRequest,
                                              RequestOptions options) throws IOException {
@@ -1450,9 +1438,9 @@ public class RestHighLevelClient implements Closeable {
             throw new IOException("Unable to parse response body for " + response, e);
         }
     }
-    
+
     /**
-     * Defines a helper method for requests that can 404 and in which case will return an empty Optional 
+     * Defines a helper method for requests that can 404 and in which case will return an empty Optional
      * otherwise tries to parse the response body
      */
     protected final <Req extends Validatable, Resp> Optional<Resp> performRequestAndParseOptionalEntity(Req request,
@@ -1481,7 +1469,7 @@ public class RestHighLevelClient implements Closeable {
         } catch (Exception e) {
             throw new IOException("Unable to parse response body for " + response, e);
         }
-    }      
+    }
 
     /**
      * @deprecated If creating a new HLRC ReST API call, consider creating new actions instead of reusing server actions. The Validation
@@ -1603,9 +1591,9 @@ public class RestHighLevelClient implements Closeable {
             }
         };
     }
-    
+
     /**
-     * Async request which returns empty Optionals in the case of 404s or parses entity into an Optional
+     * Asynchronous request which returns empty {@link Optional}s in the case of 404s or parses entity into an Optional
      */
     protected final <Req extends Validatable, Resp> void performRequestAsyncAndParseOptionalEntity(Req request,
             CheckedFunction<Req, Request, IOException> requestConverter,
@@ -1625,11 +1613,11 @@ public class RestHighLevelClient implements Closeable {
             return;
         }
         req.setOptions(options);
-        ResponseListener responseListener = wrapResponseListener404sOptional(response -> parseEntity(response.getEntity(), 
+        ResponseListener responseListener = wrapResponseListener404sOptional(response -> parseEntity(response.getEntity(),
                 entityParser), listener);
-        client.performRequestAsync(req, responseListener);        
-    }    
-    
+        client.performRequestAsync(req, responseListener);
+    }
+
     final <Resp> ResponseListener wrapResponseListener404sOptional(CheckedFunction<Response, Resp, IOException> responseConverter,
             ActionListener<Optional<Resp>> actionListener) {
         return new ResponseListener() {
@@ -1658,7 +1646,7 @@ public class RestHighLevelClient implements Closeable {
                 }
             }
         };
-    }    
+    }
 
     /**
      * Converts a {@link ResponseException} obtained from the low level REST client into an {@link ElasticsearchException}.

docs/java-rest/high-level/execution.asciidoc

@@ -18,6 +18,15 @@ for the +{response}+ to be returned before continuing with code execution:
 include-tagged::{doc-tests-file}[{api}-execute]
 --------------------------------------------------
 
+Synchronous calls may throw an `IOException` in case of either failing to
+parse the REST response in the high-level REST client, the request times out
+or similar cases where there is no response coming back from the server.
+
+In cases where the server returns a `4xx` or `5xx` error code, the high-level
+client tries to parse the response body error details instead and then throws
+a generic `ElasticsearchException` and adds the original `ResponseException` as a
+suppressed exception to it.
+
 [id="{upid}-{api}-async"]
 ==== Asynchronous Execution
 
@@ -36,7 +45,8 @@ the execution completes
 The asynchronous method does not block and returns immediately. Once it is
 completed the `ActionListener` is called back using the `onResponse` method
 if the execution successfully completed or using the `onFailure` method if
-it failed.
+it failed. Failure scenarios and expected exceptions are the same as in the
+synchronous execution case.
 
 A typical listener for +{api}+ looks like:
 
@@ -45,4 +55,4 @@ A typical listener for +{api}+ looks like:
 include-tagged::{doc-tests-file}[{api}-execute-listener]
 --------------------------------------------------
 <1> Called when the execution is successfully completed.
-<2> Called when the whole +{request}+ fails.
+<2> Called when the whole +{request}+ fails.