Document interceptor throwing modes

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())
+ *   }
+ * ```
  */
 interface Interceptor {
   @Throws(IOException::class)