Timeout allows limiting the time of the request execution or execution steps such as a connection or a TCP packet awaiting. The following timeout types are available:

• request timeout — time-bound of the whole request processing,
• connect timeout — time-bound of the connection establishment,
• socket timeout — time-bound of the interval between any two subsequent packets (read/write timeout).

By default all these timeouts are infinite and should be explicitly specified when needed. Timeouts could be specified for all requests of a particular client or for a single request.

Install

Request, connect and socket timeouts could be specified for all requests of a particular client it the configuration specified during the feature installation:

val client = HttpClient() {
    install(HttpTimeout) {
        // timeout config
        requestTimeoutMillis = 1000
    }
}

Besides that, all timeouts could also be specified for a single request and so that override high-level values:

val client = HttpClient() {
    install(HttpTimeout)
}

client.get<String>(url) {
    timeout {
        // timeout config
        requestTimeoutMillis = 5000
    }
}

Be aware that to assign per-request timeout it’s still required to have timeout feature installed. In case per-request configuration is specified without installed feature an IllegalArgumentException will be thrown with message “Consider install HttpTimeout feature because request requires it to be installed”.

In case of timeout an exception will be thrown. The type of exception depends on type of occured timeout: HttpRequestTimeoutException in case of request timeout, HttpConnectTimeoutException in case of connect timeout and HttpSocketTimeoutException in case of socket timeout.

Platform-specific behaviour

Not all client engines support all timeout types. Curl doesn’t support socket timeout, Ios doesn’t support connect timeout and Js supports only request timeout.