Skip to content

Change Log

Version 4.1.0


  • OkHttp’s new okhttp-brotli module implements Brotli compression. Install the interceptor to enable Brotli compression, which compresses 5-20% smaller than gzip.

    val client = OkHttpClient.Builder()

    This artifact has a dependency on Google’s Brotli decoder (95 KiB).

  • New: EventListener.proxySelectStart(), proxySelectEnd() events give visibility into the proxy selection process.

  • New: Response.byteString() reads the entire response into memory as a byte string.
  • New: OkHttpClient.x509TrustManager accessor.
  • New: Permit new WebSocket response codes: 1012 (Service Restart), 1013 (Try Again Later), and 1014 (invalid response from the upstream).
  • New: Build with Kotlin 1.3.41, BouncyCastle 1.62, and Conscrypt 2.2.1.
  • Fix: Recover gracefully when a a coalesced connection immediately goes unhealthy.
  • Fix: Defer the SecurityException when looking up the default proxy selector.
  • Fix: Don’t use brackets formatting IPv6 host names in MockWebServer.
  • Fix: Don’t permit cache iterators to remove entries that are being written.

Version 4.0.1


  • Fix: Tolerate null-hostile lists in public API. Lists created with List.of(...) don’t like it when you call contains(null) on them!
  • Fix: Retain binary-compatibility in okhttp3.internal.HttpHeaders.hasBody(). Some unscrupulous coders call this and we don’t want their users to suffer.

Version 4.0.0


This release upgrades OkHttp to Kotlin. We tried our best to make fast and safe to upgrade from OkHttp 3.x. We wrote an upgrade guide to help with the migration and a blog post to explain it.

  • Fix: Target Java 8 bytecode for Java and Kotlin.

Version 4.0.0-RC3


  • Fix: Retain binary-compatibility in okhttp3.internal.HttpMethod. Naughty third party SDKs import this and we want to ease upgrades for their users.

Version 4.0.0-RC2


  • New: Require Kotlin 1.3.40.
  • New: Change the Kotlin API from File.toRequestBody() to File.asRequestBody() and BufferedSource.toResponseBody() to BufferedSource.asResponseBody(). If the returned value is a view of what created it, we use as.
  • Fix: Permit response codes of zero for compatibility with OkHttp 3.x.
  • Fix: Change the return type of MockWebServer.takeRequest() to be nullable.
  • Fix: Make Call.clone() public to Kotlin callers.

Version 4.0.0-RC1


  • First stable preview of OkHttp 4.

Version 3.14.2


  • Fix: Lock in a route when recovering from an HTTP/2 connection error. We had a bug where two calls that failed at the same time could cause OkHttp to crash with a NoSuchElementException instead of the expected IOException.

  • Fix: Don’t crash with a NullPointerException when formatting an error message describing a truncated response from an HTTPS proxy.

Version 3.12.3


  • Fix: Permit multipart file names to contain non-ASCII characters.
  • Fix: Retain the Route when a connection is reused on a redirect or other follow-up. This was causing some Authenticator calls to see a null route when non-null was expected.

Version 3.14.1


  • Fix: Don’t crash when an interceptor retries when there are no more routes. This was an edge-case regression introduced with the events cleanup in 3.14.0.

  • Fix: Provide actionable advice when the exchange is non-null. Prior to 3.14, OkHttp would silently leak connections when an interceptor retries without closing the response body. With 3.14 we detect this problem but the exception was not helpful.

Version 3.14.0


  • This release deletes the long-deprecated OkUrlFactory and OkApacheClient APIs. These facades hide OkHttp’s implementation behind another client’s API. If you still need this please copy and paste or into your project.

  • OkHttp now supports duplex calls over HTTP/2. With normal HTTP calls the request must finish before the response starts. With duplex, request and response bodies are transmitted simultaneously. This can be used to implement interactive conversations within a single HTTP call.

    Create duplex calls by overriding the new RequestBody.isDuplex() method to return true. This simple option dramatically changes the behavior of the request body and of the entire call.

    The RequestBody.writeTo() method may now retain a reference to the provided sink and hand it off to another thread to write to it after writeTo returns.

    The EventListener may now see requests and responses interleaved in ways not previously permitted. For example, a listener may receive responseHeadersStart() followed by requestBodyEnd(), both on the same call. Such events may be triggered by different threads even for a single call.

    Interceptors that rewrite or replace the request body may now inadvertently interfere with duplex request bodies. Such interceptors should check RequestBody.isDuplex() and avoid accessing the request body when it is.

    Duplex calls require HTTP/2. If HTTP/1 is established instead the duplex call will fail. The most common use of duplex calls is gRPC.

  • New: Prevent OkHttp from retransmitting a request body by overriding RequestBody.isOneShot(). This is most useful when writing the request body is destructive.

  • New: We’ve added requestFailed() and responseFailed() methods to EventListener. These are called instead of requestBodyEnd() and responseBodyEnd() in some failure situations. They may also be fired in cases where no event was published previously. In this release we did an internal rewrite of our event code to fix problems where events were lost or unbalanced.

  • Fix: Don’t leak a connection when a call is canceled immediately preceding the onFailure() callback.

  • Fix: Apply call timeouts when connecting duplex calls, web sockets, and server-sent events. Once the streams are established no further timeout is enforced.

  • Fix: Retain the Route when a connection is reused on a redirect or other follow-up. This was causing some Authenticator calls to see a null route when non-null was expected.

  • Fix: Use the correct key size in the name of TLS_AES_128_CCM_8_SHA256 which is a TLS 1.3 cipher suite. We accidentally specified a key size of 256, preventing that cipher suite from being selected for any TLS handshakes. We didn’t notice because this cipher suite isn’t supported on Android, Java, or Conscrypt.

    We removed this cipher suite and TLS_AES_128_CCM_SHA256 from the restricted, modern, and compatible sets of cipher suites. These two cipher suites aren’t enabled by default in either Firefox or Chrome.

    See our TLS Configuration History tracker for a log of all changes to OkHttp’s default TLS options.

  • New: Upgrade to Conscrypt 2.0.0. OkHttp works with other versions of Conscrypt but this is the version we’re testing against.

  • New: Update the embedded public suffixes list.

Version 3.12.2


  • Fix: Don’t crash if the HTTPS server returns no certificates in the TLS handshake.
  • Fix: Don’t leak a connection when a call is canceled immediately preceding the onFailure() callback.

Version 3.13.1


  • Fix: Don’t crash when using a custom X509TrustManager or SSLSocket on Android. When we removed obsolete code for Android 4.4 we inadvertently also removed support for custom subclasses. We’ve restored that support!

Version 3.13.0


  • This release bumps our minimum requirements to Java 8+ or Android 5+. Cutting off old devices is a serious change and we don’t do it lightly! This post explains why we’re doing this and how to upgrade.

    The OkHttp 3.12.x branch will be our long-term branch for Android 2.3+ (API level 9+) and Java 7+. These platforms lack support for TLS 1.2 and should not be used. But because upgrading is difficult we will backport critical fixes to the 3.12.x branch through December 31, 2020.

  • TLSv1 and TLSv1.1 are no longer enabled by default. Major web browsers are working towards removing these versions altogether in early 2020. If your servers aren’t ready yet you can configure OkHttp 3.13 to allow TLSv1 and TLSv1.1 connections:

    OkHttpClient client = new OkHttpClient.Builder()
  • New: You can now access HTTP trailers with Response.trailers(). This method may only be called after the entire HTTP response body has been read.

  • New: Upgrade to Okio 1.17.3. If you’re on Kotlin-friendly Okio 2.x this release requires 2.2.2 or newer.

  • Fix: Don’t miss cancels when sending HTTP/2 request headers.

  • Fix: Don’t miss whole operation timeouts when calls redirect.
  • Fix: Don’t leak connections if web sockets have malformed responses or if onOpen() throws.
  • Fix: Don’t retry when request bodies fail due to FileNotFoundException.
  • Fix: Don’t crash when URLs have IPv4-mapped IPv6 addresses.
  • Fix: Don’t crash when building HandshakeCertificates on Android API 28.
  • Fix: Permit multipart file names to contain non-ASCII characters.
  • New: API to get MockWebServer’s dispatcher.
  • New: API to access headers as java.time.Instant.
  • New: Fail fast if a SSLSocketFactory is used as a SocketFactory.
  • New: Log the TLS handshake in LoggingEventListener.

Version 3.12.1


  • Fix: Remove overlapping This caused issues with some build tools.

Version 3.12.0


  • OkHttp now supports TLS 1.3. This requires either Conscrypt or Java 11+.

  • Proxy authenticators are now asked for preemptive authentication. OkHttp will now request authentication credentials before creating TLS tunnels through HTTP proxies (HTTP CONNECT). Authenticators should identify preemptive authentications by the presence of a challenge whose scheme is “OkHttp-Preemptive”.

  • OkHttp now offers full-operation timeouts. This sets a limit on how long the entire call may take and covers resolving DNS, connecting, writing the request body, server processing, and reading the full response body. If a call requires redirects or retries all must complete within one timeout period.

    Use OkHttpClient.Builder.callTimeout() to specify the default duration and Call.timeout() to specify the timeout of an individual call.

  • New: Return values and fields are now non-null unless otherwise annotated.

  • New: LoggingEventListener makes it easy to get basic visibility into a call’s performance. This class is in the logging-interceptor artifact.
  • New: Headers.Builder.addUnsafeNonAscii() allows non-ASCII values to be added without an immediate exception.
  • New: Headers can be redacted in HttpLoggingInterceptor.
  • New: Headers.Builder now accepts dates.
  • New: OkHttp now accepts java.time.Duration for timeouts on Java 8+ and Android 26+.
  • New: Challenge includes all authentication parameters.
  • New: Upgrade to BouncyCastle 1.60, Conscrypt 1.4.0, and Okio 1.15.0. We don’t yet require Kotlin-friendly Okio 2.x but OkHttp works fine with that series.

  • Fix: Handle dispatcher executor shutdowns gracefully. When there aren’t any threads to carry a call its callback now gets a RejectedExecutionException.

  • Fix: Don’t permanently cache responses with Cache-Control: immutable. We misunderstood the original immutable proposal!
  • Fix: Change Authenticator‘s Route parameter to be nullable. This was marked as non-null but could be called with null in some cases.
  • Fix: Don’t create malformed URLs when MockWebServer is reached via an IPv6 address.
  • Fix: Don’t crash if the system default authenticator is null.
  • Fix: Don’t crash generating elliptic curve certificates on Android.
  • Fix: Don’t crash doing platform detection on RoboVM.
  • Fix: Don’t leak socket connections when web socket upgrades fail.

Version 3.11.0


  • OkHttp’s new okhttp-tls submodule tames HTTPS and TLS.

    HeldCertificate is a TLS certificate and its private key. Generate a certificate with its builder then use it to sign another certificate or perform a TLS handshake. The certificatePem() method encodes the certificate in the familiar PEM format (--- BEGIN CERTIFICATE ---); the privateKeyPkcs8Pem() does likewise for the private key.

    HandshakeCertificates holds the TLS certificates required for a TLS handshake. On the server it keeps your HeldCertificate and its chain. On the client it keeps the root certificates that are trusted to sign a server’s certificate chain. HandshakeCertificates also works with mutual TLS where these roles are reversed.

    These classes make it possible to enable HTTPS in MockWebServer in just a few lines of code.

  • OkHttp now supports prior knowledge cleartext HTTP/2. Enable this by setting Protocol.H2_PRIOR_KNOWLEDGE as the lone protocol on an OkHttpClient.Builder. This mode only supports http: URLs and is best suited in closed environments where HTTPS is inappropriate.

  • New: HttpUrl.get(String) is an alternative to HttpUrl.parse(String) that throws an exception when the URL is malformed instead of returning null. Use this to avoid checking for null in situations where the input is known to be well-formed. We’ve also added MediaType.get(String) which is an exception-throwing alternative to MediaType.parse(String).

  • New: The EventListener API previewed in OkHttp 3.9 has graduated to a stable API. Use this interface to track metrics and monitor HTTP requests’ size and duration.
  • New: okhttp-dnsoverhttps is an experimental API for doing DNS queries over HTTPS. Using HTTPS for DNS offers better security and potentially better performance. This feature is a preview: the API is subject to change.
  • New: okhttp-sse is an early preview of Server-Sent Events (SSE). This feature is incomplete and is only suitable for experimental use.
  • New: MockWebServer now supports client authentication (mutual TLS). Call requestClientAuth() to permit an optional client certificate or requireClientAuth() to require one.
  • New: RecordedRequest.getHandshake() returns the HTTPS handshake of a request sent to MockWebServer.
  • Fix: Honor the MockResponse header delay in MockWebServer.
  • Fix: Don’t release HTTP/2 connections that have multiple canceled calls. We had a bug where canceling calls would cause the shared HTTP/2 connection to be unnecessarily released. This harmed connection reuse.
  • Fix: Ensure canceled and discarded HTTP/2 data is not permanently counted against the limited flow control window. We had a few bugs where window size accounting was broken when streams were canceled or reset.
  • Fix: Recover gracefully if the TLS session returns an unexpected version (NONE) or cipher suite (SSL_NULL_WITH_NULL_NULL).
  • Fix: Don’t change Conscrypt configuration globally. We migrated from a process-wide setting to configuring only OkHttp’s TLS sockets.
  • Fix: Prefer TLSv1.2 where it is available. On certain older platforms it is necessary to opt-in to TLSv1.2.
  • New: Request.tag() permits multiple tags. Use a Class<?> as a key to identify tags. Note that tag() now returns null if the request has no tag. Previously this would return the request itself.
  • New: Headers.Builder.addAll(Headers).
  • New: ResponseBody.create(MediaType, ByteString).
  • New: Embed R8/ProGuard rules in the jar. These will be applied automatically by R8.
  • Fix: Release the connection if Authenticator throws an exception.
  • Fix: Change the declaration of OkHttpClient.cache() to return a @Nullable Cache. The return value has always been nullable but it wasn’t declared properly.
  • Fix: Reverse suppression of connect exceptions. When both a call and its retry fail, we now throw the initial exception which is most likely to be actionable.
  • Fix: Retain interrupted state when throwing InterruptedIOException. A single interrupt should now be sufficient to break out an in-flight OkHttp call.
  • Fix: Don’t drop a call to EventListener.callEnd() when the response body is consumed inside an interceptor.

Version 3.10.0


  • The pingInterval() feature now aggressively checks connectivity for web sockets and HTTP/2 connections.

    Previously if you configured a ping interval that would cause OkHttp to send pings, but it did not track whether the reply pongs were received. With this update OkHttp requires that every ping receive a response: if it does not the connection will be closed and the listener’s onFailure() method will be called.

    Web sockets have always been had pings, but pings on HTTP/2 connections is new in this release. Pings are used for connections that are busy carrying calls and for idle connections in the connection pool. (Pings do not impact when pooled connections are evicted).

    If you have a configured ping interval, you should confirm that it is long enough for a roundtrip from client to server. If your ping interval is too short, slow connections may be misinterpreted as failed connections. A ping interval of 30 seconds is reasonable for most use cases.

  • OkHttp now supports Conscrypt. Conscrypt is a Java Security Provider that integrates BoringSSL into the Java platform. Conscrypt supports more cipher suites than the JVM’s default provider and may also execute more efficiently.

    To use it, first register a Conscrypt dependency in your build system.

    OkHttp will use Conscrypt if you set the okhttp.platform system property to conscrypt.

    Alternatively, OkHttp will also use Conscrypt if you install it as your preferred security provider. To do so, add the following code to execute before you create your OkHttpClient.

        new org.conscrypt.OpenSSLProvider(), 1);

    Conscrypt is the bundled security provider on Android so it is not necessary to configure it on that platform.

  • New: HttpUrl.addQueryParameter() percent-escapes more characters. Previously several ASCII punctuation characters were not percent-escaped when used with this method. This does not impact already-encoded query parameters in APIs like HttpUrl.parse() and HttpUrl.Builder.addEncodedQueryParameter().

  • New: CBC-mode ECDSA cipher suites have been removed from OkHttp’s default configuration: TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA and TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA. This tracks a Chromium change to remove these cipher suites because they are fragile and rarely-used.
  • New: Don’t fall back to common name (CN) verification for hostnames. This behavior was deprecated with RFC 2818 in May 2000 and was recently dropped from major web browsers.
  • New: Honor the Retry-After response header. HTTP 503 (Unavailable) responses are retried automatically if this header is present and its delay is 0 seconds. HTTP 408 (Client Timeout) responses are retried automatically if the header is absent or its delay is 0 seconds.
  • New: Allow request bodies for all HTTP methods except GET and HEAD.
  • New: Automatic module name of okhttp3 for use with the Java Platform Module System.
  • New: Log gzipped bodies when HttpLoggingInterceptor is used as a network interceptor.
  • New: Protocol.QUIC constant. This protocol is not supported but this constant is included for completeness.
  • New: Upgrade to Okio 1.14.0.

  • Fix: Handle HTTP/1.1 100 Continue status lines, even on requests that did not send the Expect: continue request header.

  • Fix: Do not count web sockets toward the dispatcher’s per-host connection limit.
  • Fix: Avoid using invalid HTTPS sessions. This prevents OkHttp from crashing with the error, Unexpected TLS version: NONE.
  • Fix: Don’t corrupt the response cache when a 304 (Not Modified) response overrides the stored “Content-Encoding” header.
  • Fix: Gracefully shut down the HTTP/2 connection before it exhausts the namespace of stream IDs (~536 million streams).
  • Fix: Never pass a null Route to Authenticator. There was a bug where routes were omitted for eagerly-closed connections.

Version 3.9.1


  • New: Recover gracefully when Android’s DNS crashes with an unexpected NullPointerException.
  • New: Recover gracefully when Android’s socket connections crash with an unexpected ClassCastException.
  • Fix: Don’t include the URL’s fragment in encodedQuery() when the query itself is empty.

Version 3.9.0


  • Interceptors are more capable. The Chain interface now offers access to the call and can adjust all call timeouts. Note that this change is source-incompatible for code that implements the Chain interface. We don’t expect this to be a problem in practice!

  • OkHttp has an experimental new API for tracking metrics. The new EventListener API is designed to help developers monitor HTTP requests’ size and duration. This feature is an unstable preview: the API is subject to change, and the implementation is incomplete. This is a big new API we are eager for feedback.

  • New: Support ALPN via Google Play Services’ Dynamic Security Provider. This expands HTTP/2 support to older Android devices that have Google Play Services.

  • New: Consider all routes when looking for candidate coalesced connections. This increases the likelihood that HTTP/2 connections will be shared.
  • New: Authentication challenges and credentials now use a charset. Use this in your authenticator to support user names and passwords with non-ASCII characters.
  • New: Accept a charset in FormBody.Builder. Previously form bodies were always UTF-8.
  • New: Support the immutable cache-control directive.
  • Fix: Don’t crash when an HTTP/2 call is redirected while the connection is being shut down.
  • Fix: Don’t drop headers of healthy streams that raced with GOAWAY frames. This bug would cause HTTP/2 streams to occasional hang when the connection was shutting down.
  • Fix: Honor OkHttpClient.retryOnConnectionFailure() when the response is a HTTP 408 Request Timeout. If retries are enabled, OkHttp will retry exactly once in response to a 408.
  • Fix: Don’t crash when reading the empty HEAD response body if it specifies a Content-Length.
  • Fix: Don’t crash if the thread is interrupted while reading the public suffix database.
  • Fix: Use relative resource path when loading the public suffix database. Loading the resource using a path relative to the class prevents conflicts when the OkHttp classes are relocated (shaded) by allowing multiple private copies of the database.
  • Fix: Accept cookies for URLs that have an IPv6 address for a host.
  • Fix: Don’t log the protocol (HTTP/1.1, h2) in HttpLoggingInterceptor if the protocol isn’t negotiated yet! Previously we’d log HTTP/1.1 by default, and this was confusing.
  • Fix: Omit the message from MockWebServer’s HTTP/2 :status header.
  • Fix: Handle ‘Expect: 100 Continue’ properly in MockWebServer.

Version 3.8.1


  • Fix: Recover gracefully from stale coalesced connections. We had a bug where connection coalescing (introduced in OkHttp 3.7.0) and stale connection recovery could interact to cause a NoSuchElementException crash in the RouteSelector.

Version 3.8.0


  • OkHttp now uses @Nullable to annotate all possibly-null values. We’ve added a compile-time dependency on the JSR 305 annotations. This is a provided dependency and does not need to be included in your build configuration, .jar file, or .apk. We use @ParametersAreNonnullByDefault and all parameters and return types are never null unless explicitly annotated @Nullable.

  • Warning: this release is source-incompatible for Kotlin users. Nullability was previously ambiguous and lenient but now the compiler will enforce strict null checks.

  • New: The response message is now non-null. This is the “Not Found” in the status line “HTTP 404 Not Found”. If you are building responses programmatically (with new Response.Builder()) you must now always supply a message. An empty string "" is permitted. This value was never null on responses returned by OkHttp itself, and it was an old mistake to permit application code to omit a message.

  • The challenge’s scheme and realm are now non-null. If you are calling new Challenge(scheme, realm) you must provide non-null values. These were never null in challenges created by OkHttp, but could have been null in application code that creates challenges.

  • New: The TlsVersion of a Handshake is now non-null. If you are calling Handshake.get() with a null TLS version, you must instead now provide a non-null TlsVersion. Cache responses persisted prior to OkHttp 3.0 did not store a TLS version; for these unknown values the handshake is defaulted to TlsVersion.SSL_3_0.

  • New: Upgrade to Okio 1.13.0.

  • Fix: gracefully recover when Android 7.0’s sockets throw an unexpected NullPointerException.

Version 3.7.0


  • OkHttp no longer recovers from TLS handshake failures by attempting a TLSv1 connection. The fallback was necessary for servers that implemented version negotiation incorrectly. Now that 99.99% of servers do it right this fallback is obsolete.
  • Fix: Do not honor cookies set on a public domain. Previously a malicious site could inject cookies on top-level domains like because our cookie parser didn’t honor the public suffix list. Alongside this fix is a new API, HttpUrl.topPrivateDomain(), which returns the privately domain name if the URL has one.
  • Fix: Change MediaType.charset() to return null for unexpected charsets.
  • Fix: Don’t skip cache invalidation if the invalidating response has no body.
  • Fix: Don’t use a cryptographic random number generator for web sockets. Some Android devices implement SecureRandom incorrectly!
  • Fix: Correctly canonicalize IPv6 addresses in HttpUrl. This prevented OkHttp from trusting HTTPS certificates issued to certain IPv6 addresses.
  • Fix: Don’t reuse connections after an unsuccessful Expect: 100-continue.
  • Fix: Handle either TLS_ or SSL_ prefixes for cipher suite names. This is necessary for IBM JVMs that use the SSL_ prefix exclusively.
  • Fix: Reject HTTP/2 data frames if the stream ID is 0.
  • New: Upgrade to Okio 1.12.0.

  • New: Connection coalescing. OkHttp may reuse HTTP/2 connections across calls that share an IP address and HTTPS certificate, even if their domain names are different.

  • New: MockWebServer’s RecordedRequest exposes the requested HttpUrl with getRequestUrl().

Version 3.6.0


  • Fix: Don’t crash with a “cache is closed” error when there is an error initializing the cache.
  • Fix: Calling disconnect() on a connecting HttpUrlConnection could cause it to retry in an infinite loop! This regression was introduced in OkHttp 2.7.0.
  • Fix: Drop cookies that contain ASCII NULL and other bad characters. Previously such cookies would cause OkHttp to crash when they were included in a request.
  • Fix: Release duplicated multiplexed connections. If we concurrently establish connections to an HTTP/2 server, close all but the first connection.
  • Fix: Fail the HTTP/2 connection if first frame isn’t SETTINGS.
  • Fix: Forbid spaces in header names.
  • Fix: Don’t offer to do gzip if the request is partial.
  • Fix: MockWebServer is now usable with JUnit 5. That update broke the rules.
  • New: Support Expect: 100-continue as a request header. Callers can use this header to pessimistically hold off on transmitting a request body until a server gives the go-ahead.
  • New: Permit network interceptors to rewrite the host header for HTTP/2. This makes it possible to do domain fronting.
  • New: charset support for Credentials.basic().

Version 3.5.0


  • Web Sockets are now a stable feature of OkHttp. Since being introduced as a beta feature in OkHttp 2.3 our web socket client has matured. Connect to a server’s web socket with OkHttpClient.newWebSocket(), send messages with send(), and receive messages with the WebSocketListener.

    The okhttp-ws submodule is no longer available and okhttp-ws artifacts from previous releases of OkHttp are not compatible with OkHttp 3.5. When upgrading to the new package please note that the WebSocket and WebSocketCall classes have been merged. Sending messages is now asynchronous and they may be enqueued before the web socket is connected.

  • OkHttp no longer attempts a direct connection if the system’s HTTP proxy fails. This behavior was surprising because OkHttp was disregarding the user’s specified configuration. If you need to customize proxy fallback behavior, implement your own

  • Fix: Support TLSv1.3 on devices that support it.

  • Fix: Share pooled connections across equivalent OkHttpClient instances. Previous releases had a bug where a shared connection pool did not guarantee shared connections in some cases.

  • Fix: Prefer the server’s response body on all conditional cache misses. Previously we would return the cached response’s body if it had a newer Last-Modified date.
  • Fix: Update the stored timestamp on conditional cache hits.
  • New: Optimized HTTP/2 request header encoding. More headers are HPACK-encoded and string literals are now Huffman-encoded.
  • New: Expose Part headers and body in Multipart.
  • New: Make ResponseBody.string() and ResponseBody.charStream() BOM-aware. If your HTTP response body begins with a byte order mark it will be consumed and used to select a charset for the remaining bytes. Most applications should not need a byte order mark.

  • New: Upgrade to Okio 1.11.0.

  • Fix: Avoid sending empty HTTP/2 data frames when there is no request body.

  • Fix: Add a leading . for better domain matching in JavaNetCookieJar.
  • Fix: Gracefully recover from HTTP/2 connection shutdowns at start of request.
  • Fix: Be lenient if a MediaType‘s character set is 'single-quoted'.
  • Fix: Allow horizontal tab characters in header values.
  • Fix: When parsing HTTP authentication headers permit challenge parameters in any order.

Version 3.4.2


  • Fix: Recover gracefully when an HTTP/2 connection is shutdown. We had a bug where shutdown HTTP/2 connections were considered usable. This caused infinite loops when calls attempted to recover.

Version 3.4.1


  • Fix a major bug in encoding HTTP headers. In 3.4.0 and 3.4.0-RC1 OkHttp had an off-by-one bug in our HPACK encoder. This bug could have caused the wrong headers to be emitted after a sequence of HTTP/2 requests! Everyone who is using OkHttp 3.4.0 or 3.4.0-RC1 should upgrade for this bug fix.

Version 3.4.0


  • New: Support dynamic table size changes to HPACK Encoder.
  • Fix: Use TreeMap in Headers.toMultimap(). This makes string lookups on the returned map case-insensitive.
  • Fix: Don’t share the OkHttpClient’s Dispatcher in HttpURLConnection.

Version 3.4.0-RC1


  • We’ve rewritten HttpURLConnection and HttpsURLConnection. Previously we shared a single HTTP engine between two frontend APIs: HttpURLConnection and Call. With this release we’ve rearranged things so that the HttpURLConnection frontend now delegates to the Call APIs internally. This has enabled substantial simplifications and optimizations in the OkHttp core for both frontends.

    For most HTTP requests the consequences of this change will be negligible. If your application uses HttpURLConnection.connect(), setFixedLengthStreamingMode(), or setChunkedStreamingMode(), OkHttp will now use a async dispatcher thread to establish the HTTP connection.

    We don’t expect this change to have any behavior or performance consequences. Regardless, please exercise your OkUrlFactory and HttpURLConnection code when applying this update.

  • Cipher suites may now have arbitrary names. Previously CipherSuite was a Java enum and it was impossible to define new cipher suites without first upgrading OkHttp. With this change it is now a regular Java class with enum-like constants. Application code that uses enum methods on cipher suites (ordinal(), name(), etc.) will break with this change.

  • Fix: CertificatePinner now matches canonicalized hostnames. Previously this was case sensitive. This change should also make it easier to configure certificate pinning for internationalized domain names.

  • Fix: Don’t crash on non-ASCII ETag headers. Previously OkHttp would reject these headers when validating a cached response.
  • Fix: Don’t allow remote peer to arbitrarily size the HPACK decoder dynamic table.
  • Fix: Honor per-host configuration in Android’s network security config. Previously disabling cleartext for any host would disable cleartext for all hosts. Note that this setting is only available on Android 24+.
  • New: HPACK compression is now dynamic. This should improve performance when transmitting request headers over HTTP/2.
  • New: Dispatcher.setIdleCallback() can be used to signal when there are no calls in flight. This is useful for testing with Espresso.
  • New: Upgrade to Okio 1.9.0.


Version 3.3.1


  • Fix: The plaintext check in HttpLoggingInterceptor incorrectly classified newline characters as control characters. This is fixed.
  • Fix: Don’t crash reading non-ASCII characters in HTTP/2 headers or in cached HTTP headers.
  • Fix: Retain the response body when an attempt to open a web socket returns a non-101 response code.

Version 3.3.0


  • New: Response.sentRequestAtMillis() and receivedResponseAtMillis() methods track the system’s local time when network calls are made. These replace the OkHttp-Sent-Millis and OkHttp-Received-Millis headers that were present in earlier versions of OkHttp.
  • New: Accept user-provided trust managers in OkHttpClient.Builder. This allows OkHttp to satisfy its TLS requirements directly. Otherwise OkHttp will use reflection to extract the TrustManager from the SSLSocketFactory.
  • New: Support prerelease Java 9. This gets ALPN from the platform rather than relying on the alpn-boot bootclasspath override.
  • New: HttpLoggingInterceptor now logs connection failures.
  • New: Upgrade to Okio 1.8.0.

  • Fix: Gracefully recover from a failure to rebuild the cache journal.

  • Fix: Don’t corrupt cache entries when a cache entry is evicted while it is being updated.
  • Fix: Make logging more consistent throughout OkHttp.
  • Fix: Log plaintext bodies only. This uses simple heuristics to differentiate text from other data.
  • Fix: Recover from REFUSED_STREAM errors in HTTP/2. This should improve interoperability with Nginx 1.10.0, which refuses streams created before HTTP/2 settings have been acknowledged.
  • Fix: Improve recovery from failed routes.
  • Fix: Accommodate tunneling proxies that close the connection after an auth challenge.
  • Fix: Use the proxy authenticator when authenticating HTTP proxies. This regression was introduced in OkHttp 3.0.
  • Fix: Fail fast if network interceptors transform the response body such that closing it doesn’t also close the underlying stream. We had a bug where OkHttp would attempt to reuse a connection but couldn’t because it was still held by a prior request.
  • Fix: Ensure network interceptors always have access to the underlying connection.
  • Fix: Use X509TrustManagerExtensions on Android 17+.
  • Fix: Unblock waiting dispatchers on MockWebServer shutdown.

Version 3.2.0


  • Fix: Change the certificate pinner to always build full chains. This prevents a potential crash when using certificate pinning with the Google Play Services security provider.
  • Fix: Make IPv6 request lines consistent with Firefox and Chrome.
  • Fix: Recover gracefully when trimming the response cache fails.
  • New: Add multiple path segments using a single string in HttpUrl.Builder.
  • New: Support SHA-256 pins in certificate pinner.

Version 3.1.2


  • Fix: Don’t crash when finding the trust manager on Robolectric. We attempted to detect the host platform and got confused because Robolectric looks like Android but isn’t!
  • Fix: Change CertificatePinner to skip sanitizing the certificate chain when no certificates were pinned. This avoids an SSL failure in insecure “trust everyone” configurations, such as when talking to a development HTTPS server that has a self-signed certificate.

Version 3.1.1


  • Fix: Don’t crash when finding the trust manager if the Play Services (GMS) security provider is installed.
  • Fix: The previous release introduced a performance regression on Android, caused by looking up CA certificates. This is now fixed.

Version 3.1.0


  • New: WebSockets now defer some writes. This should improve performance for some applications.
  • New: Override equals() and hashCode() in our new cookie class. This class now defines equality by value rather than by reference.
  • New: Handle 408 responses by retrying the request. This allows servers to direct clients to retry rather than failing permanently.
  • New: Expose the framed protocol in Connection. Previously this would return the application-layer protocol (HTTP/1.1 or HTTP/1.0); now it always returns the wire-layer protocol (HTTP/2, SPDY/3.1, or HTTP/1.1).
  • Fix: Permit the trusted CA root to be pinned by CertificatePinner.
  • Fix: Silently ignore unknown HTTP/2 settings. Previously this would cause the entire connection to fail.
  • Fix: Don’t crash on unexpected charsets in the logging interceptor.
  • Fix: OkHttpClient is now non-final for the benefit of mocking frameworks. Mocking sophisticated classes like OkHttpClient is fragile and you shouldn’t do it. But if that’s how you want to live your life we won’t stand in your way!

Version 3.0.1


  • Rollback OSGi support. This was causing library jars to include more classes than expected, which interfered with Gradle builds.

Version 3.0.0


This release commits to a stable 3.0 API. Read the 3.0.0-RC1 changes for advice on upgrading from 2.x to 3.x.

  • The Callback interface now takes a Call. This makes it easier to check if the call was canceled from within the callback. When migrating async calls to this new API, Call is now the first parameter for both onResponse() and onFailure().
  • Fix: handle multiple cookies in JavaNetCookieJar on Android.
  • Fix: improve the default HTTP message in MockWebServer responses.
  • Fix: don’t leak file handles when a conditional GET throws.
  • Fix: Use charset specified by the request body content type in OkHttp’s logging interceptor.
  • Fix: Don’t eagerly release pools on cache hits.
  • New: Make OkHttp OSGi ready.
  • New: Add already-implemented interfaces Closeable and Flushable to the cache.

Version 3.0.0-RC1


OkHttp 3 is a major release focused on API simplicity and consistency. The API changes are numerous but most are cosmetic. Applications should be able to upgrade from the 2.x API to the 3.x API mechanically and without risk.

Because the release includes breaking API changes, we’re changing the project’s package name from com.squareup.okhttp to okhttp3. This should make it possible for large applications to migrate incrementally. The Maven group ID is now com.squareup.okhttp3. For an explanation of this strategy, see Jake Wharton’s post, Java Interoperability Policy for Major Version Updates.

This release obsoletes OkHttp 2.x, and all code that uses OkHttp’s com.squareup.okhttp package should upgrade to the okhttp3 package. Libraries that depend on OkHttp should upgrade quickly to prevent applications from being stuck on the old version.

  • There is no longer a global singleton connection pool. In OkHttp 2.x, all OkHttpClient instances shared a common connection pool by default. In OkHttp 3.x, each new OkHttpClient gets its own private connection pool. Applications should avoid creating many connection pools as doing so prevents connection reuse. Each connection pool holds its own set of connections alive so applications that have many pools also risk exhausting memory!

    The best practice in OkHttp 3 is to create a single OkHttpClient instance and share it throughout the application. Requests that needs a customized client should call OkHttpClient.newBuilder() on that shared instance. This allows customization without the drawbacks of separate connection pools.

  • OkHttpClient is now stateless. In the 2.x API OkHttpClient had getters and setters. Internally each request was forced to make its own complete snapshot of the OkHttpClient instance to defend against racy configuration changes. In 3.x, OkHttpClient is now stateless and has a builder. Note that this class is not strictly immutable as it has stateful members like the connection pool and cache.

  • Get and Set prefixes are now avoided. With ubiquitous builders throughout OkHttp these accessor prefixes aren’t necessary. Previously OkHttp used get and set prefixes sporadically which make the API inconsistent and awkward to explore.

  • OkHttpClient now implements the new Call.Factory interface. This interface will make your code easier to test. When you test code that makes HTTP requests, you can use this interface to replace the real OkHttpClient with your own mocks or fakes.

    The interface will also let you use OkHttp’s API with another HTTP client’s implementation. This is useful in sandboxed environments like Google App Engine.

  • OkHttp now does cookies. We’ve replaced with a new interface, CookieJar and added our own Cookie model class. This new cookie follows the latest RFC and supports the same cookie attributes as modern web browsers.

  • Form and Multipart bodies are now modeled. We’ve replaced the opaque FormEncodingBuilder with the more powerful FormBody and FormBody.Builder combo. Similarly we’ve upgraded MultipartBuilder into MultipartBody, MultipartBody.Part, and MultipartBody.Builder.

  • The Apache HTTP client and HttpURLConnection APIs are deprecated. They continue to work as they always have, but we’re moving everything to the new OkHttp 3 API. The okhttp-apache and okhttp-urlconnection modules should be only be used to accelerate a transition to OkHttp’s request/response API. These deprecated modules will be dropped in an upcoming OkHttp 3.x release.

  • Canceling batches of calls is now the application’s responsibility. The API to cancel calls by tag has been removed and replaced with a more general mechanism. The dispatcher now exposes all in-flight calls via its runningCalls() and queuedCalls() methods. You can write code that selects calls by tag, host, or whatever, and invokes Call.cancel() on the ones that are no longer necessary.

  • OkHttp no longer uses the global by default. We’ve changed our Authenticator interface to authenticate web and proxy authentication failures through a single method. An adapter for the old authenticator is available in the okhttp-urlconnection module.

  • Fix: Don’t throw IOException on ResponseBody.contentLength() or close().

  • Fix: Never throw converting an HttpUrl to a This changes the uri() method to handle malformed percent-escapes and characters forbidden by URI.
  • Fix: When a connect times out, attempt an alternate route. Previously route selection was less efficient when differentiating failures.
  • New: Response.peekBody() lets you access the response body without consuming it. This may be handy for interceptors!
  • New: HttpUrl.newBuilder() resolves a link to a builder.
  • New: Add the TLS version to the Handshake.
  • New: Drop Request.uri() and Request#urlString(). Just use Request.url().uri() and Request.url().toString().
  • New: Add URL to HTTP response logging.
  • New: Make HttpUrl the blessed URL method of Request.

Version 2.7.5


  • Fix: Change the certificate pinner to always build full chains. This prevents a potential crash when using certificate pinning with the Google Play Services security provider.

Version 2.7.4


  • Fix: Don’t crash when finding the trust manager if the Play Services (GMS) security provider is installed.
  • Fix: The previous release introduced a performance regression on Android, caused by looking up CA certificates. This is now fixed.

Version 2.7.3


  • Fix: Permit the trusted CA root to be pinned by CertificatePinner.

Version 2.7.2


  • Fix: Don’t eagerly release stream allocations on cache hits. We might still need them to handle redirects.

Version 2.7.1


  • Fix: Don’t do a health check on newly-created connections. This is unnecessary work that could put the client in an inconsistent state if the health check fails.

Version 2.7.0


  • Rewritten connection management. Previously OkHttp’s connection pool managed both idle and active connections for HTTP/2, but only idle connections for HTTP/1.x. With this update the connection pool manages both idle and active connections for everything. OkHttp now detects and warns on connections that were allocated but never released, and will enforce HTTP/2 stream limits. This update also fixes Call.cancel() to not do I/O on the calling thread.
  • Fix: Don’t log gzipped data in the logging interceptor.
  • Fix: Don’t resolve DNS addresses when connecting through a SOCKS proxy.
  • Fix: Drop the synthetic OkHttp-Selected-Protocol response header.
  • Fix: Support 204 and 205 ‘No Content’ replies in the logging interceptor.
  • New: Add Call.isExecuted().

Version 2.6.0


  • New Logging Interceptor. The logging-interceptor subproject offers simple request and response logging. It may be configured to log headers and bodies for debugging. It requires this Maven dependency:


    Configure basic logging like this:

    HttpLoggingInterceptor loggingInterceptor = new HttpLoggingInterceptor();

    Warning: Avoid Level.HEADERS and Level.BODY in production because they could leak passwords and other authentication credentials to insecure logs.

  • WebSocket API now uses RequestBody and ResponseBody for messages. This is a backwards-incompatible API change.

  • The DNS service is now pluggable. In some situations this may be useful to manually prioritize specific IP addresses.

  • Fix: Don’t throw when converting an HttpUrl to a Previously URLs with special characters like | and [ would break when subjected to URI’s overly-strict validation.

  • Fix: Don’t re-encode + as %20 in encoded URL query strings. OkHttp prefers %20 when doing its own encoding, but will retain + when that is provided.
  • Fix: Enforce that callers call WebSocket.close() on IO errors. Error handling in WebSockets is significantly improved.
  • Fix: Don’t use SPDY/3 style header concatenation for HTTP/2 request headers. This could have corrupted requests where multiple headers had the same name, as in cookies.
  • Fix: Reject bad characters in the URL hostname. Previously characters like \0 would cause a late crash when building the request.
  • Fix: Allow interceptors to change the request method.
  • Fix: Don’t use the request’s User-Agent or Proxy-Authorization when connecting to an HTTPS server via an HTTP tunnel. The Proxy-Authorization header was being leaked to the origin server.
  • Fix: Digits may be used in a URL scheme.
  • Fix: Improve connection timeout recovery.
  • Fix: Recover from getsockname crashes impacting Android releases prior to 4.2.2.
  • Fix: Drop partial support for HTTP/1.0. Previously OkHttp would send HTTP/1.0 on connections after seeing a response with HTTP/1.0. The fixed behavior is consistent with Firefox and Chrome.
  • Fix: Allow a body in OPTIONS requests.
  • Fix: Don’t percent-encode non-ASCII characters in URL fragments.
  • Fix: Handle null fragments.
  • Fix: Don’t crash on interceptors that throw IOException before a connection is attempted.
  • New: Support WebDAV HTTP methods.
  • New: Buffer WebSocket frames for better performance.
  • New: Drop support for TLS_DHE_DSS_WITH_AES_128_CBC_SHA, our only remaining DSS cipher suite. This is consistent with Firefox and Chrome which have also dropped these cipher suite.

Version 2.5.0


  • Timeouts now default to 10 seconds. Previously we defaulted to never timing out, and that was a lousy policy. If establishing a connection, reading the next byte from a connection, or writing the next byte to a connection takes more than 10 seconds to complete, you’ll need to adjust the timeouts manually.

  • OkHttp now rejects request headers that contain invalid characters. This includes potential security problems (newline characters) as well as simple non-ASCII characters (including international characters and emoji).

  • Call canceling is more reliable. We had a bug where a socket being connected wasn’t being closed when the application used Call.cancel().

  • Changing a HttpUrl’s scheme now tracks the default port. We had a bug where changing a URL from http to https would leave it on port 80.

  • Okio has been updated to 1.6.0.


  • New: Cache.initialize(). Call this on a background thread to eagerly initialize the response cache.

  • New: Fold MockWebServerRule into MockWebServer. This makes it easier to write JUnit tests with MockWebServer. The MockWebServer library now depends on JUnit, though it continues to work with all testing frameworks.
  • Fix: FormEncodingBuilder is now consistent with browsers in which characters it escapes. Previously we weren’t percent-encoding commas, parens, and other characters.
  • Fix: Relax FormEncodingBuilder to support building empty forms.
  • Fix: Timeouts throw SocketTimeoutException, not InterruptedIOException.
  • Fix: Change MockWebServer to use the same logic as OkHttp when determining whether an HTTP request permits a body.
  • Fix: HttpUrl now uses the canonical form for IPv6 addresses.
  • Fix: Use HttpUrl internally.
  • Fix: Recover from Android 4.2.2 EBADF crashes.
  • Fix: Don’t crash with an IllegalStateException if an HTTP/2 or SPDY write fails, leaving the connection in an inconsistent state.
  • Fix: Make sure the default user agent is ASCII.

Version 2.4.0


  • Forbid response bodies on HTTP 204 and 205 responses. Webservers that return such malformed responses will now trigger a ProtocolException in the client.

  • WebSocketListener has incompatible changes. The onOpen() method is now called on the reader thread, so implementations must return before further websocket messages will be delivered. The onFailure() method now includes an HTTP response if one was returned.

Version 2.4.0-RC1


  • New HttpUrl API. It’s like but good. Note that Request.Builder.url() now throws IllegalArgumentException on malformed URLs. (Previous releases would throw a MalformedURLException when calling a malformed URL.)

  • We’ve improved connect failure recovery. We now differentiate between setup, connecting, and connected and implement appropriate recovery rules for each. This changes Address to no longer use ConnectionSpec. (This is an incompatible API change).

  • FormEncodingBuilder now uses %20 instead of + for encoded spaces. Both are permitted-by-spec, but %20 requires fewer special cases.

  • Okio has been updated to 1.4.0.


  • Request.Builder no longer accepts null if a request body is required. Passing null will now fail for request methods that require a body. Instead use an empty body such as this one:

        RequestBody.create(null, new byte[0]);
  • CertificatePinner now supports wildcard hostnames. As always with certificate pinning, you must be very careful to avoid bricking your app. You’ll need to pin both the top-level domain and the *. domain for full coverage.

     client.setCertificatePinner(new CertificatePinner.Builder()
         .add("",   "sha1/DmxUShsZuNiqPQsX2Oi9uv2sCnw=")
         .add("*", "sha1/DmxUShsZuNiqPQsX2Oi9uv2sCnw=")
         .add("",   "sha1/SXxoaOSEzPC6BgGmxAt/EAcsajw=")
         .add("*", "sha1/SXxoaOSEzPC6BgGmxAt/EAcsajw=")
         .add("",   "sha1/blhOM3W9V/bVQhsWAcLYwPU6n24=")
         .add("*", "sha1/blhOM3W9V/bVQhsWAcLYwPU6n24=")
         .add("",   "sha1/T5x9IXmcrQ7YuQxXnxoCmeeQ84c=")
         .add("*", "sha1/T5x9IXmcrQ7YuQxXnxoCmeeQ84c=")
  • Interceptors lists are now deep-copied by OkHttpClient.clone(). Previously clones shared interceptors, which made it difficult to customize the interceptors on a request-by-request basis.

  • New: Headers.toMultimap().

  • New: RequestBody.create(MediaType, ByteString).
  • New: ConnectionSpec.isCompatible(SSLSocket).
  • New: Dispatcher.getQueuedCallCount() and Dispatcher.getRunningCallCount(). These can be useful in diagnostics.
  • Fix: OkHttp no longer shares timeouts between pooled connections. This was causing some applications to crash when connections were reused.
  • Fix: OkApacheClient now allows an empty PUT and POST.
  • Fix: Websockets no longer rebuffer socket streams.
  • Fix: Websockets are now better at handling close frames.
  • Fix: Content type matching is now case insensitive.
  • Fix: Vary headers are not lost with
  • Fix: HTTP/2 wasn’t enforcing stream timeouts when writing the underlying connection. Now it is.
  • Fix: Never return null on call.proceed(). This was a bug in call cancelation.
  • Fix: When a network interceptor mutates a request, that change is now reflected in Response.networkResponse().
  • Fix: Badly-behaving caches now throw a checked exception instead of a NullPointerException.
  • Fix: Better handling of uncaught exceptions in MockWebServer with HTTP/2.

Version 2.3.0


  • HTTP/2 support. We’ve done interop testing and haven’t seen any problems. HTTP/2 support has been a big effort and we’re particularly thankful to Adrian Cole who has helped us to reach this milestone.

  • RC4 cipher suites are no longer supported by default. To connect to old, obsolete servers relying on these cipher suites, you must create a custom ConnectionSpec.

  • Beta WebSockets support.. The okhttp-ws subproject offers a new websockets client. Please try it out! When it’s ready we intend to include it with the core OkHttp library.

  • Okio updated to 1.3.0.

  • Fix: improve parallelism of async requests. OkHttp’s Dispatcher had a misconfigured ExecutorService that limited the number of worker threads. If you’re using Call.enqueue() this update should significantly improve request concurrency.

  • Fix: Lazily initialize the response cache. This avoids strict mode warnings when initializing OkHttp on Android‘s main thread.

  • Fix: Disable ALPN on Android 4.4. That release of the feature was unstable and prone to native crashes in the underlying OpenSSL code.

  • Fix: Don’t send both If-None-Match and If-Modified-Since cache headers when both are applicable.
  • Fix: Fail early when a port is out of range.
  • Fix: Offer Content-Length headers for multipart request bodies.
  • Fix: Throw UnknownServiceException if a cleartext connection is attempted when explicitly forbidden.
  • Fix: Throw a SSLPeerUnverifiedException when host verification fails.
  • Fix: MockWebServer explicitly closes sockets. (On some Android releases, closing the input stream and output stream of a socket is not sufficient.
  • Fix: Buffer outgoing HTTP/2 frames to limit how many outgoing frames are created.
  • Fix: Avoid crashing when cache writing fails due to a full disk.
  • Fix: Improve caching of private responses.
  • Fix: Update cache-by-default response codes.
  • Fix: Reused Request.Builder instances no longer hold stale URL fields.
  • New: ConnectionSpec can now be configured to use the SSL socket’s default cipher suites. To use, set the cipher suites to null.
  • New: Support DELETE with a request body.
  • New: Headers.of(Map) creates headers from a Map.

Version 2.2.0


  • RequestBody.contentLength() now throws IOException. This is a source-incompatible change. If you have code that calls RequestBody.contentLength(), your compile will break with this update. The change is binary-compatible, however: code compiled for OkHttp 2.0 and 2.1 will continue to work with this update.

  • COMPATIBLE_TLS no longer supports SSLv3. In response to the POODLE vulnerability, OkHttp no longer offers SSLv3 when negotiation an HTTPS connection. If you continue to need to connect to webservers running SSLv3, you must manually configure your own ConnectionSpec.

  • OkHttp now offers interceptors. Interceptors are a powerful mechanism that can monitor, rewrite, and retry calls. The interceptors doc is a full introduction to this new API.

  • New: APIs to iterate and selectively clear the response cache.

  • New: Support for SOCKS proxies.
  • New: Support for TLS_FALLBACK_SCSV.
  • New: Update HTTP/2 support to h2-16 and hpack-10.
  • New: APIs to prevent retrying non-idempotent requests.
  • Fix: Drop NPN support. Going forward we support ALPN only.
  • Fix: The hostname verifier is now strict. This is consistent with the hostname verifier in modern browsers.
  • Fix: Improve CONNECT handling for misbehaving HTTP proxies.
  • Fix: Don’t retry requests that failed due to timeouts.
  • Fix: Cache 302s and 308s that include appropriate response headers.
  • Fix: Improve pooling of connections that use proxy selectors.
  • Fix: Don’t leak connections when using ALPN on the desktop.
  • Fix: Update Jetty ALPN to 7.1.2.v20141202 (Java 7) and 8.1.2.v20141202 (Java 8). This fixes a bug in resumed TLS sessions where the wrong protocol could be selected.
  • Fix: Don’t crash in SPDY and HTTP/2 when disconnecting before connecting.
  • Fix: Avoid a reverse DNS-lookup for a numeric proxy address
  • Fix: Resurrect http/2 frame logging.
  • Fix: Limit to 20 authorization attempts.

Version 2.1.0


  • New: Typesafe APIs for interacting with cipher suites and TLS versions.
  • Fix: Don’t crash when mixing authorization challenges with upload retries.

Version 2.1.0-RC1


  • OkHttp now caches private responses. We’ve changed from a shared cache to a private cache, and will now store responses that use an Authorization header. This means OkHttp’s cache shouldn’t be used on middleboxes that sit between user agents and the origin server.

  • TLS configuration updated. OkHttp now explicitly enables TLSv1.2, TLSv1.1 and TLSv1.0 where they are supported. It will continue to perform only one fallback, to SSLv3. Applications can now configure this with the ConnectionSpec class.

    To disable TLS fallback:

        ConnectionSpec.MODERN_TLS, ConnectionSpec.CLEARTEXT));

    To disable cleartext connections, permitting https URLs only:

        ConnectionSpec.MODERN_TLS, ConnectionSpec.COMPATIBLE_TLS));
  • New cipher suites. Please confirm that your webservers are reachable with this limited set of cipher suites.

    Name                                     Version
    TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256    5.0
    TLS_DHE_RSA_WITH_AES_128_GCM_SHA256      5.0
    TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA       4.0
    TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA       4.0
    TLS_ECDHE_ECDSA_WITH_RC4_128_SHA         4.0
    TLS_ECDHE_RSA_WITH_RC4_128_SHA           4.0
    TLS_DHE_RSA_WITH_AES_128_CBC_SHA         2.3
    TLS_DHE_DSS_WITH_AES_128_CBC_SHA         2.3
    TLS_DHE_RSA_WITH_AES_256_CBC_SHA         2.3
    TLS_RSA_WITH_AES_128_GCM_SHA256          5.0
    TLS_RSA_WITH_AES_128_CBC_SHA             2.3
    TLS_RSA_WITH_AES_256_CBC_SHA             2.3
    SSL_RSA_WITH_3DES_EDE_CBC_SHA            2.3  (Deprecated in 5.0)
    SSL_RSA_WITH_RC4_128_SHA                 2.3
    SSL_RSA_WITH_RC4_128_MD5                 2.3  (Deprecated in 5.0)
  • Okio updated to 1.0.1.

  • New APIs to permit easy certificate pinning. Be warned, certificate pinning is dangerous and could prevent your application from trusting your server!

  • Cache improvements. This release fixes some severe cache problems including a bug where the cache could be corrupted upon certain access patterns. We also fixed a bug where the cache was being cleared due to a corrupted journal. We’ve added APIs to configure a request’s Cache-Control headers, and to manually clear the cache.

  • Request cancellation fixes. This update fixes a bug where synchronous requests couldn’t be canceled by tag. This update avoids crashing when onResponse() throws an IOException. That failure will now be logged instead of notifying the thread’s uncaught exception handler. We’ve added a new API, Call.isCanceled() to check if a call has been canceled.

  • New: Update MultipartBuilder to support content length.

  • New: Make it possible to mock OkHttpClient and Call.
  • New: Update to h2-14 and hpack-9.
  • New: OkHttp includes a user-agent by default, like okhttp/2.1.0-RC1.
  • Fix: Handle response code 308 Permanent Redirect.
  • Fix: Don’t skip the callback if a call is canceled.
  • Fix: Permit hostnames with underscores.
  • Fix: Permit overriding the content-type in OkApacheClient.
  • Fix: Use the socket factory for direct connections.
  • Fix: Honor OkUrlFactory APIs that disable redirects.
  • Fix: Don’t crash on concurrent modification of SPDY SPDY settings.

Version 2.0.0

This release commits to a stable 2.0 API. Read the 2.0.0-RC1 changes for advice on upgrading from 1.x to 2.x.


  • API Change: Use IOException in Callback.onFailure(). This is a source-incompatible change, and is different from OkHttp 2.0.0-RC2 which used Throwable.
  • Fix: Fixed a caching bug where we weren’t storing rewritten request headers like Accept-Encoding.
  • Fix: Fixed bugs in handling the SPDY window size. This was stalling certain large downloads
  • Update the language level to Java 7. (OkHttp requires Android 2.3+ or Java 7+.)

Version 2.0.0-RC2


This update fixes problems in 2.0.0-RC1. Read the 2.0.0-RC1 changes for advice on upgrading from 1.x to 2.x.

  • Fix: Don’t leak connections! There was a regression in 2.0.0-RC1 where connections were neither closed nor pooled.
  • Fix: Revert builder-style return types from OkHttpClient’s timeout methods for binary compatibility with OkHttp 1.x.
  • Fix: Don’t skip client stream 1 on SPDY/3.1. This fixes SPDY connectivity to, which doesn’t follow the SPDY/3.1 spec!
  • Fix: Always configure NPN headers. This fixes connectivity to when SPDY and HTTP/2 are both disabled. Otherwise an unexpected NPN response is received and OkHttp crashes.
  • Fix: Write continuation frames when HPACK data is larger than 16383 bytes.
  • Fix: Don’t drop uncaught exceptions thrown in async calls.
  • Fix: Throw an exception eagerly when a request body is not legal. Previously we ignored the problem at request-building time, only to crash later with a NullPointerException.
  • Fix: Include a backwards-compatible OkHttp-Response-Source header with OkUrlFactoryresponses.
  • Fix: Don’t include a default User-Agent header in requests made with the Call API. Requests made with OkUrlFactory will continue to have a default user agent.
  • New: Guava-like API to create headers:

    Headers headers = Headers.of(name1, value1, name2, value2, ...).
  • New: Make the content-type header optional for request bodies.

  • New: Response.isSuccessful() is a convenient API to check response codes.
  • New: The response body can now be read outside of the callback. Response bodies must always be closed, otherwise they will leak connections!
  • New: APIs to create multipart request bodies (MultipartBuilder) and form encoding bodies (FormEncodingBuilder).

Version 2.0.0-RC1


OkHttp 2 is designed around a new API that is true to HTTP, with classes for requests, responses, headers, and calls. It uses modern Java patterns like immutability and chained builders. The API now offers asynchronous callbacks in addition to synchronous blocking calls.

API Changes

  • New Request and Response types, each with their own builder. There’s also a RequestBody class to write the request body to the network and a ResponseBody to read the response body from the network. The standalone Headers class offers full access to the HTTP headers.

  • Okio dependency added. OkHttp now depends on Okio, an I/O library that makes it easier to access, store and process data. Using this library internally makes OkHttp faster while consuming less memory. You can write a RequestBody as an Okio BufferedSink and a ResponseBody as an Okio BufferedSource. Standard InputStream and OutputStream access is also available.

  • New Call and Callback types execute requests and receive their responses. Both types of calls can be canceled via the Call or the OkHttpClient.

  • URLConnection support has moved to the okhttp-urlconnection module. If you’re upgrading from 1.x, this change will impact you. You will need to add the okhttp-urlconnection module to your project and use the OkUrlFactory to create new instances of HttpURLConnection:

    // OkHttp 1.x:
    HttpURLConnection connection =;
    // OkHttp 2.x:
    HttpURLConnection connection = new OkUrlFactory(client).open(url);
  • Custom caches are no longer supported. In OkHttp 1.x it was possible to define your own response cache with the and OkHttp’s OkResponseCache interfaces. Both of these APIs have been dropped. In OkHttp 2 the built-in disk cache is the only supported response cache.

  • HttpResponseCache has been renamed to Cache. Install it with OkHttpClient.setCache(...) instead of OkHttpClient.setResponseCache(...).

  • OkAuthenticator has been replaced with Authenticator. This new authenticator has access to the full incoming response and can respond with whichever followup request is appropriate. The Challenge class is now a top-level class and Credential is replaced with a utility class called Credentials.

  • OkHttpClient.getFollowProtocolRedirects() renamed to getFollowSslRedirects(). We reserve the word protocol for the HTTP version being used (HTTP/1.1, HTTP/2). The old name of this method was misleading; it was always used to configure redirects between https:// and http:// schemes.

  • RouteDatabase is no longer public API. OkHttp continues to track which routes have failed but this is no exposed in the API.

  • ResponseSource is gone. This enum exposed whether a response came from the cache, network, or both. OkHttp 2 offers more detail with raw access to the cache and network responses in the new Response class.

  • TunnelRequest is gone. It specified how to connect to an HTTP proxy. OkHttp 2 uses the new Request class for this.

  • Dispatcher is a new class that manages the queue of asynchronous calls. It implements limits on total in-flight calls and in-flight calls per host.

Implementation changes

  • Support Android TrafficStats socket tagging.
  • Drop authentication headers on redirect.
  • Added support for compressed data frames.
  • Process push promise callbacks in order.
  • Update to http/2 draft 12.
  • Update to HPACK draft 07.
  • Add ALPN support. Maven will use ALPN on OpenJDK 8.
  • Update NPN dependency to target jdk7u60-b13 and Oracle jdk7u55-b13.
  • Ensure SPDY variants support zero-length DELETE and POST.
  • Prevent leaking a cache item’s InputStreams when metadata read fails.
  • Use a string to identify TLS versions in routes.
  • Add frame logger for HTTP/2.
  • Replacing httpMinorVersion with Protocol. Expose HTTP/1.0 as a potential protocol.
  • Use Protocol to describe framing.
  • Implement write timeouts for HTTP/1.1 streams.
  • Avoid use of SPDY stream ID 1, as that’s typically used for UPGRADE.
  • Support OAuth in Authenticator.
  • Permit a dangling semicolon in media type parsing.

Version 1.6.0


  • Offer bridges to make it easier to migrate from OkHttp 1.x to OkHttp 2.0. This adds OkUrlFactory, Cache, and @Deprecated annotations for APIs dropped in 2.0.

Version 1.5.4


  • Drop ALPN support in Android. There’s a concurrency bug in all currently-shipping versions.
  • Support asynchronous disconnects by breaking the socket only. This should prevent flakiness from multiple threads concurrently accessing a stream.

Version 1.5.3


  • Fix bug where the Content-Length header was not always dropped when following a redirect from a POST to a GET.
  • Implement basic support for Thread.interrupt(). OkHttp now checks for an interruption before doing a blocking call. If it is interrupted, it throws an InterruptedIOException.

Version 1.5.2


  • Fix bug where deleting a file that was absent from the HttpResponseCache caused an IOException.
  • Fix bug in HTTP/2 where our HPACK decoder wasn’t emitting entries in certain eviction scenarios, leading to dropped response headers.

Version 1.5.1


  • Fix 1.5.0 regression where connections should not have been recycled.
  • Fix 1.5.0 regression where transparent Gzip was broken by attempting to recover from another I/O failure.
  • Fix problems where spdy/3.1 headers may not have been compressed properly.
  • Fix problems with spdy/3.1 and http/2 where the wrong window size was being used.
  • Fix 1.5.0 regression where conditional cache responses could corrupt the connection pool.

Version 1.5.0


OkHttp no longer uses the default SSL context.

Applications that want to use the global SSL context with OkHttp should configure their OkHttpClient instances with the following:


A simpler solution is to avoid the shared default SSL socket factory. Instead, if you need to customize SSL, do so for your specific OkHttpClient instance only.

Synthetic headers have changed

Previously OkHttp added a synthetic response header, OkHttp-Selected-Transport. It has been replaced with a new synthetic header, OkHttp-Selected-Protocol.

  • New: Support for HTTP-draft-09/2.0.
  • New: Support for spdy/3.1. Dropped support for spdy/3.
  • New: Use ALPN on Android platforms that support it (4.4+)
  • New: CacheControl model and parser.
  • New: Protocol selection in MockWebServer.
  • Fix: Route selection shouldn’t use TLS modes that we know will fail.
  • Fix: Cache SPDY responses even if the response body is closed prematurely.
  • Fix: Use strict timeouts when aborting a download.
  • Fix: Support Shoutcast HTTP responses like ICY 200 OK.
  • Fix: Don’t unzip if there isn’t a response body.
  • Fix: Don’t leak gzip streams on redirects.
  • Fix: Don’t do DNS lookups on invalid hosts.
  • Fix: Exhaust the underlying stream when reading gzip streams.
  • Fix: Support the PATCH method.
  • Fix: Support request bodies on DELETE method.
  • Fix: Drop the okhttp-protocols module.
  • Internal: Replaced internal byte array buffers with pooled buffers (“OkBuffer”).

Version 1.3.0


  • New: Support for “PATCH” HTTP method in client and MockWebServer.
  • Fix: Drop Content-Length header when redirected from POST to GET.
  • Fix: Correctly read cached header entries with malformed header names.
  • Fix: Do not directly support any authentication schemes other than “Basic”.
  • Fix: Respect read timeouts on recycled connections.
  • Fix: Transmit multiple cookie values as a single header with delimiter.
  • Fix: Ensure null is never returned from a connection’s getHeaderFields().
  • Fix: Persist proper Content-Encoding header to cache for GZip responses.
  • Fix: Eliminate rare race condition in SPDY streams that would prevent connection reuse.
  • Fix: Change HTTP date formats to UTC to conform to RFC2616 section 3.3.
  • Fix: Support SPDY header blocks with trailing bytes.
  • Fix: Allow ; as separator for Cache-Control header.
  • Fix: Correct bug where HTTPS POST requests were always automatically buffered.
  • Fix: Honor read timeout when parsing SPDY headers.

Version 1.2.1


  • Resolve issue with ‘jar-with-dependencies’ artifact creation.
  • Fix: Support empty SPDY header values.

Version 1.2.0


  • New APIs on OkHttpClient to set default timeouts for connect and read.
  • Fix bug when caching SPDY responses.
  • Fix a bug with SPDY plus half-closed streams. (thanks kwuollett)
  • Fix a bug in Content-Length reporting for gzipped streams in the Apache HTTP client adapter. (thanks kwuollett)
  • Work around the Alcatel getByInetAddress bug (thanks k.kocel)
  • Be more aggressive about testing pooled sockets before reuse. (thanks warpspin)
  • Include Content-Type and Content-Encoding in the Apache HTTP client adapter. (thanks kwuollett)
  • Add a media type class to OkHttp.
  • Change custom header prefix:

    X-Android-Sent-Millis is now OkHttp-Sent-Millis
    X-Android-Received-Millis is now OkHttp-Received-Millis
    X-Android-Response-Source is now OkHttp-Response-Source
    X-Android-Selected-Transport is now OkHttp-Selected-Transport
    * Improve cache invalidation for POST-like requests. * Bring MockWebServer into OkHttp and teach it SPDY.

Version 1.1.1


  • Fix: ClassCastException when caching responses that were redirected from HTTP to HTTPS.

Version 1.1.0


  • Fix: Connection reuse was broken for most HTTPS connections due to a bug in the way the hostname verifier was selected.
  • Fix: Locking bug in SpdyConnection.
  • Fix: Ignore null header values (for compatibility with HttpURLConnection).
  • Add URLStreamHandlerFactory support so that URL.openConnection() uses OkHttp.
  • Expose the transport (“http/1.1”, “spdy/3”, etc.) via magic request headers. Use X-Android-Transports to write the preferred transports and X-Android-Selected-Transport to read the negotiated transport.

Version 1.0.2


  • Fix: Remove use of Java 6-only APIs.
  • Fix: Properly handle exceptions from NetworkInterface when querying MTU.
  • Fix: Ensure MTU has a reasonable default and upper-bound.

Version 1.0.1


  • Correct casing of SSL in method names (getSslSocketFactory/setSslSocketFactory).

Version 1.0.0


Initial release.