diff --git a/kubernetes-client-api/src/main/java/io/fabric8/kubernetes/client/http/Interceptor.java b/kubernetes-client-api/src/main/java/io/fabric8/kubernetes/client/http/Interceptor.java
index f85ad595930..581fca1954c 100644
--- a/kubernetes-client-api/src/main/java/io/fabric8/kubernetes/client/http/Interceptor.java
+++ b/kubernetes-client-api/src/main/java/io/fabric8/kubernetes/client/http/Interceptor.java
@@ -19,6 +19,13 @@
 import java.util.List;
 import java.util.concurrent.CompletableFuture;
 
+/**
+ * A collection of callback methods invoked through the various stages of the HTTP request lifecycle.
+ * Each invocation of {@link Interceptor#before(BasicBuilder, HttpRequest, RequestTags)} will be matched with a call to one of
+ * {@link Interceptor#afterConnectionFailure(HttpRequest, Throwable)} or
+ * {@link Interceptor#after(HttpRequest, HttpResponse, AsyncBody.Consumer)}.
+ * Callbacks that lead to a request being sent allow for that request to be customised.
+ */
 public interface Interceptor {
 
   interface RequestTags {
@@ -63,7 +70,10 @@ default AsyncBody.Consumer<List<ByteBuffer>> consumer(AsyncBody.Consumer<List<By
   }
 
   /**
-   * Called after a websocket failure or by default from a normal request
+   * Called after a websocket failure or by default from a normal request.
+   * <p>
+   * Failure is determined by HTTP status code and will be invoked in addition to {@see Interceptor#after(HttpRequest,
+   * HttpResponse, AsyncBody.Consumer)}
    *
    * @param builder used to modify the request
    * @param response the failed response
@@ -75,7 +85,10 @@ default CompletableFuture<Boolean> afterFailure(BasicBuilder builder, HttpRespon
 
   /**
    * Called after a non-websocket failure
-   *
+   * <p>
+   * Failure is determined by HTTP status code and will be invoked in addition to {@see Interceptor#after(HttpRequest,
+   * HttpResponse, AsyncBody.Consumer)}
+   * 
    * @param builder used to modify the request
    * @param response the failed response
    * @return true if the builder should be used to execute a new request