From 8c2f383f14e354a45d0f9f16f5b0fa35b7244a51 Mon Sep 17 00:00:00 2001
From: Jesse Wilson <jesse@swank.ca>
Date: Wed, 9 Sep 2020 21:48:06 -0400
Subject: [PATCH] Document interceptor throwing modes (#6235)

---
 okhttp/src/main/kotlin/okhttp3/Interceptor.kt | 33 +++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/okhttp/src/main/kotlin/okhttp3/Interceptor.kt b/okhttp/src/main/kotlin/okhttp3/Interceptor.kt
index 8da5b803d468..fa601c34fdac 100644
--- a/okhttp/src/main/kotlin/okhttp3/Interceptor.kt
+++ b/okhttp/src/main/kotlin/okhttp3/Interceptor.kt
@@ -22,6 +22,39 @@ import java.util.concurrent.TimeUnit
  * Observes, modifies, and potentially short-circuits requests going out and the corresponding
  * responses coming back in. Typically interceptors add, remove, or transform headers on the request
  * or response.
+ *
+ * Implementations of this interface throw [IOException] to signal connectivity failures. This
+ * includes both natural exceptions such as unreachable servers, as well as synthetic exceptions
+ * when responses are of an unexpected type or cannot be decoded.
+ *
+ * Other exception types cancel the current call:
+ *
+ *  * For synchronous calls made with [Call.execute], the exception is propagated to the caller.
+ *
+ *  * For asynchronous calls made with [Call.enqueue], an [IOException] is propagated to the caller
+ *    indicating that the call was canceled. The interceptor's exception is delivered to the current
+ *    thread's [uncaught exception handler][Thread.UncaughtExceptionHandler]. By default this
+ *    crashes the application on Android and prints a stacktrace on the JVM. (Crash reporting
+ *    libraries may customize this behavior.)
+ *
+ * A good way to signal a failure is with a synthetic HTTP response:
+ *
+ * ```
+ *   @Throws(IOException::class)
+ *   override fun intercept(chain: Interceptor.Chain): Response {
+ *     if (myConfig.isInvalid()) {
+ *       return Response.Builder()
+ *           .request(chain.request())
+ *           .protocol(Protocol.HTTP_1_1)
+ *           .code(400)
+ *           .message("client config invalid")
+ *           .body("client config invalid".toResponseBody(null))
+ *           .build()
+ *     }
+ *
+ *     return chain.proceed(chain.request())
+ *   }
+ * ```
  */
 fun interface Interceptor {
   @Throws(IOException::class)