Client: Wrap synchronous exceptions

client/rest/src/main/java/org/elasticsearch/client/RestClient.java

@@ -203,6 +203,14 @@ public Response performRequest(String method, String endpoint, Map<String, Strin
      * they previously failed (the more failures, the later they will be retried). In case of failures all of the alive nodes (or dead
      * nodes that deserve a retry) are retried until one responds or none of them does, in which case an {@link IOException} will be thrown.
      *
+     * This method works by performing an asynchronous call and the waiting
+     * for the result. If the asynchronous call throws and exception we wrap
+     * it and rethrow it so that the stack trace attached to the exception
+     * contains the call site. While we attempt to preserve the original
+     * exception this isn't always possible and likely haven't covered all of
+     * the cases. You can get the original exception from
+     * {@link Exception#getCause()}.
+     *
      * @param method the http method
      * @param endpoint the path of the request (without host and port)
      * @param params the query_string parameters