Retrofit uses some default network timeout settings, which might not fit your use case. If your app needs to be extra snappy, or in the other direction, if your server is slow, you might want to change those timeout settings. In this tutorial you'll learn how you can customize all three special network timeouts settings.
Retrofit Series Overview
- Getting Started and Creating an Android Client
- Basics of API Description
- Creating a Sustainable Android Client
- URL Handling, Resolution and Parsing
- How to Change API Base Url at Runtime
- Multiple Server Environments (Develop, Staging, Production)
- Share OkHttp Client and Converters between Retrofit Instances
- Upgrade Guide from 1.9
- Beyond Android: Retrofit for Java Projects
- How to use OkHttp 3 with Retrofit 1
- Synchronous and Asynchronous Requests
- Send Objects in Request Body
- Add Custom Request Header
- Manage Request Headers in OkHttp Interceptor
- Dynamic Request Headers with @HeaderMap
- Multiple Query Parameters of Same Name
- Optional Query Parameters
- Send Data Form-Urlencoded
- Send Data Form-Urlencoded Using FieldMap
- How to Add Query Parameters to Every Request
- Add Multiple Query Parameter With QueryMap
- How to Use Dynamic Urls for Requests
- Constant, Default and Logic Values for POST and PUT Requests
- Cancel Requests
- Reuse and Analyze Requests
- Optional Path Parameters
- How to Send Plain Text Request Body
- Customize Network Timeouts
- How to Trust Unsafe SSL certificates (Self-signed, Expired)
- Dynamic Endpoint-Dependent Interceptor Actions
- How to Update Objects on the Server (PUT vs. PATCH)
- How to Delete Objects on the Server
- Introduction to (Multiple) Converters
- Adding & Customizing the Gson Converter
- Implementing Custom Converters
- How to Integrate XML Converter
- Access Mapped Objects and Raw Response Payload
- Supporting JSON and XML Responses Concurrently
- Handling of Empty Server Responses with Custom Converter
- Send JSON Requests and Receive XML Responses (or vice versa)
- Unwrapping Envelope Responses with Custom Converter
- Wrapping Requests in Envelope with Custom Converter
- Define a Custom Response Converter
By default, Retrofit uses the following timeouts:
- Connection timeout: ten seconds
- Read timeout: ten seconds
- Write timeout: ten seconds
We'll explain what these mean in detail in a later section.
How to Configure Timeout Settings via OkHttp
As you probably guessed, the customization of network connection timeouts on Retrofit can't be done directly. Instead, you have to configure OkHttp, Retrofit's network layer, to customize the connection timeouts:
OkHttpClient okHttpClient = new OkHttpClient.Builder() .connectTimeout(1, TimeUnit.MINUTES) .readTimeout(30, TimeUnit.SECONDS) .writeTimeout(15, TimeUnit.SECONDS) .build(); Retrofit.Builder builder = new Retrofit.Builder() .baseUrl("http://10.0.2.2:3000/") .client(okHttpClient) .addConverterFactory(GsonConverterFactory.create());
The code above sets the connection timeout to one minute, the read timeout to 30 seconds, and the write timeout to 15 seconds. Of course you don't have to change all three at the same time and can just modify whatever subset you want to modify. Let's look at each timeout in more detail.
The connection timeout is likely the most interesting timeout. It is the time that lasts from starting the request to a completed TCP handshake with the server. In other words, if Retrofit couldn't establish a connection to the server within the set connection timeout limit, it'll count the request as failed.
For example, increasing the default timeout of ten seconds to a higher value could make sense if you know your users are in conditions with bad Internet connection.
The read timeout starts to pay attention once the connection is established and then watches how fast (or slow) every byte gets transferred. If the time between two bytes gets larger than the read timeout, it'll count the request as failed. The counter resets after every incoming byte. Thus, if your response has 120 bytes and it takes five seconds between each byte, the read timeout will not be triggered and the response will take ten minutes to be completed.
Again, this is not only limited to the server. Slow read times can be caused by the Internet connection as well.
Finally, the write timeout is the opposite direction of the read timeout. It checks how fast you can send bytes to the server. Of course, it also gets reset after every successful byte. However, if sending a single byte takes longer than the configured write timeout limit, Retrofit will count the request as failed.
In this tutorial you've learned what kind of network timeout Retrofit offers in conjunction with OkHttp. You've also seen what they actually mean and how you can customize those timeout values.
Do you have further questions on this topic or about Retrofit in general? Just let us know on Twitter @futurestud_io or leave a comment below.
Enjoy coding & make it rock!