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..8f3505bfc72 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,10 @@
 import java.util.List;
 import java.util.concurrent.CompletableFuture;
 
+/**
+ * A collection of callback methods invoked through the various stages of the HTTP request lifecycle.
+ * Callbacks that lead to a request being sent allow for that request to be customised.
+ */
 public interface Interceptor {
 
   interface RequestTags {
@@ -63,7 +67,9 @@ 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 +81,9 @@ 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