kmp-ktor

Ktor Client for KMP and Android

This reference covers the Ktor client configuration traps — plugin install order, serialization flags, auth refresh, and error mapping — not the basics of a shared HttpClient, engine selection, or ContentNegotiation setup. Related: android-skills:android-data-layer (repository + the DataError error model — its canonical home), android-skills:android-retrofit (Android-only equivalent).

Plugin install order — HttpRequestRetry BEFORE HttpTimeout

The install order most often gotten wrong: installing HttpTimeout before HttpRequestRetry. Plugins run in install order for outgoing requests; retries must be able to catch timeout errors, so retry has to wrap timeout.

val json = Json { ignoreUnknownKeys = true; coerceInputValues = true; encodeDefaults = true }  // encodeDefaults: see the section below

HttpClient(engine) {
    install(ContentNegotiation) { json(json) }
    install(Auth) { bearer { /* loadTokens / refreshTokens */ } }
    install(HttpRequestRetry) {                 // BEFORE HttpTimeout
        retryOnServerErrors(maxRetries = 3)
        exponentialDelay()
    }
    install(HttpTimeout) {                       // AFTER HttpRequestRetry
        requestTimeoutMillis = 30_000; connectTimeoutMillis = 15_000; socketTimeoutMillis = 15_000
    }
}

Reversed, HttpTimeout resolves the request as failed before the retry plugin sees it, so timeouts are never retried. (Separately, the Auth plugin handles 401 refresh independently — let HttpRequestRetry cover transient/5xx failures; don't chain the two around the same status code.)

encodeDefaults = true — or protocol-constant fields silently vanish

kotlinx.serialization defaults to encodeDefaults = false, which strips any property whose value equals its declared default from the serialized output. A jsonrpc: String = "2.0" (or version = "1.0", type = "...") disappears from the payload; the server rejects every request with a generic "invalid request," and the fix is a one-line flag — found only after hours chasing HTTP-layer red herrings. Always set it for client APIs — the val json defined at the top of this file does, alongside ignoreUnknownKeys and coerceInputValues. That one configured instance is what the whole client shares: install(ContentNegotiation) { json(json) } and the WebSocket converter both take it.