DEV Community: Anubhav

Retrofit's `callFactory`: What `.client(okHttpClient)` Is really doing

Anubhav — Sun, 02 Aug 2026 07:22:50 +0000

Look at the two lines you write in almost every Retrofit setup:

Retrofit.Builder()
    .baseUrl(BASE_URL)
    .client(okHttpClient)
    .build()

The .client(okHttpClient) line is one you probably wrote once and never thought about again. It has a sibling on the same builder called .callFactory(...), and most Android developers never touch it. This article is about what .callFactory is, why it exists, and the things it lets you do that no interceptor ever will.

To get there properly, we need to start at a lower altitude than Retrofit and climb back up. By the time we reach .callFactory, it will feel obvious what it is.

The four types that carry the whole model

Before we talk about factories at all, it helps to know what actually composes an OkHttp request. Making an HTTP call breaks down into a handful of concerns: describing what you want to send, having something that can actually send it, holding onto that specific send while it is in flight, and reading what comes back. OkHttp gives each of those its own type:

OkHttpClient is the HTTP engine. It owns the connection pool, the dispatcher (a thread pool), the cache, the timeouts, and the interceptor list. Building one is expensive, so you make one and share it across your app.
Request is an immutable description of one HTTP request: a URL, a method, headers, an optional body. Building a Request sends nothing over the network.
Call is a Request bound to an OkHttp engine (a specific OkHttpClient), primed to fire but not yet fired. Single-use.
Response is what comes back after a Call fires: status, headers, body.

A useful mental model: OkHttpClient is the post office. Request is a sealed, addressed envelope sitting on your desk. Call is that envelope in the outbox, assigned to a specific post office, waiting for the mailman. Response is the letter that arrives back.

A few points worth holding onto before we move on:

Request is inert data; Call is a fireable action. A Request on its own has no engine and cannot send itself anywhere. A Call is what you get when you hand a Request to an OkHttpClient, which binds it to the engine that will actually fire it.
OkHttpClient is meant to be a singleton. The connection pool and thread pool are the reason it is cheap to reuse and expensive to duplicate. To vary its configuration, call client.newBuilder(), which produces a variant that shares the underlying pool, cache, and dispatcher.
Request is immutable too. To tweak one, call request.newBuilder(), change what you need, and .build() a new instance.

Sending a request without Retrofit

Here is the OkHttp lifecycle with no Retrofit in the picture:

// 1. The engine. Expensive; build once, share everywhere.
val client = OkHttpClient()

// 2. Describe WHAT to send. Just data: a URL, a method, headers.
//    Building this sends nothing.
val request = Request.Builder()
    .url("https://api.example.com/user/42")
    .get()
    .header("Accept", "application/json")
    .build()

// 3. Hand the request to the engine. It returns a Call.
//    Still nothing on the network. The Call is primed but unfired.
val call = client.newCall(request)

// 4. Fire it. THIS is where a socket opens and bytes move.
val response = call.execute()

// 5. Read the result.
println(response.body?.string())

Read the shape of it deliberately:

Step 2 builds a description. No I/O. You are writing the envelope.
Step 3, client.newCall(request), produces a Call. Still no I/O. The request is now bound to this specific engine and ready.
Step 4, call.execute(), is the only line that touches the network.

The interesting question is why step 3 exists as a separate step. Why isn't there just one method, client.send(request): Response? The answer to that question is the entire point of this article.

Why `Call` exists as an object

Between the moment you decide to send a request and the moment the response arrives, a lot can happen. You might want to cancel it. You might want to check whether it has been fired yet. You might want to clone it and send it again. All of that needs an object that represents the request while it is in flight, something you can hold a reference to and call methods on. That object is Call.

The interface, trimmed to essentials:

interface Call : Cloneable {
    fun request(): Request                  // read back the request I represent
    fun execute(): Response                 // fire synchronously; block until the response returns
    fun enqueue(responseCallback: Callback) // fire asynchronously; call me back later
    fun cancel()                            // abort, even mid-flight
    fun isExecuted(): Boolean               // have I already been fired?
    fun isCanceled(): Boolean
    fun clone(): Call                       // give me a fresh, unfired copy of the same request
}

Notice how many of these methods only make sense on something in flight. Take cancel(): you cannot cancel a Response, because by the time you hold one, the request is already over. Take isExecuted(): you cannot ask a Request whether it has been fired, because a Request has no engine and no live state. It is just data describing what to send. These are questions about the request's live state, not about its inputs or outputs. They need somewhere to live that is neither the Request (which has no engine) nor the Response (which is too late). The Call is that somewhere.

Before we move on to factories, two properties of Call are worth calling out.

A Call fires exactly once. Calling execute() or enqueue() on a Call that has already been fired throws IllegalStateException: Already Executed. To send the same request again, make a new Call, either by calling client.newCall(request) again or by calling call.clone():

val call = client.newCall(request)
call.execute()
call.execute()   // throws IllegalStateException: Already Executed

val fresh = call.clone()   // a new, unfired Call for the same request
fresh.execute()            // fine

A Call can be fired synchronously or asynchronously, and the only difference is which thread runs the network call. execute() is synchronous. The calling thread blocks until the full response arrives, which on Android means calling it from the main thread throws NetworkOnMainThreadException. enqueue() is asynchronous. You hand OkHttp a Callback, the line returns immediately, and OkHttp runs the request on one of its own dispatcher threads. Same Call, same request, only the waiting model differs. Retrofit's suspend functions use enqueue under the hood and bridge the callback into coroutine suspension.

`Call.Factory`: the formal name for what you have been doing

Now the reframe. Look at step 3 again:

val call = client.newCall(request)

In plain English: "client, take this request and produce a Call for me." The client, in that moment, is doing exactly one job. It is manufacturing a Call from a Request. OkHttp has a one-method interface for exactly that responsibility, nested inside the Call interface itself:

interface Call {
    // ... execute(), enqueue(), cancel(), and the rest we saw earlier

    fun interface Factory {
        fun newCall(request: Request): Call
    }
}

That nested interface is the whole contract. One method. Request in, Call out.

You have been using this interface the whole time, because OkHttpClient implements it:

open class OkHttpClient : Call.Factory, WebSocket.Factory {
    override fun newCall(request: Request): Call =
        RealCall(this, request, forWebSocket = false)
}

That gives OkHttpClient two identities at once:

As the HTTP engine, it owns the pool, dispatcher, cache, timeouts, and interceptors.
As a Call.Factory, it exposes exactly one method: newCall(request): Call.

Why `fun interface` matters

The declaration says fun interface, not plain interface. That marks it a functional interface with a single abstract method, and it changes what the Kotlin compiler will accept. You can pass a lambda anywhere a Call.Factory is expected, and the compiler will wrap the lambda body as the implementation of newCall. The two forms below are identical to the compiler:

// Explicit object
val f: Call.Factory = object : Call.Factory {
    override fun newCall(request: Request): Call = someClient.newCall(request)
}

// Lambda; Kotlin's SAM conversion produces exactly the object above
val f: Call.Factory = Call.Factory { request -> someClient.newCall(request) }

This is what makes the .callFactory { ... } lambda form on Retrofit's builder compile so cleanly. The lambda's request parameter is newCall's argument. Whatever the lambda returns is the returned Call. Hold onto this. It is why the code later in the article is as short as it is.

Small note on versioning: Call.Factory was declared fun interface in OkHttp 4.9. If you are on an older version, you need the anonymous-object form instead of the lambda form.

What Retrofit actually needs from OkHttp

Retrofit's job is to turn a Kotlin interface method into the five-step lifecycle we walked through earlier under Sending a request without Retrofit. Given:

interface UserApi {
    @GET("user/{id}")
    suspend fun getUser(@Path("id") id: String): UserDto
}

when you call api.getUser("42"), Retrofit internally:

Builds a Request from the @GET("user/{id}") annotation and the argument. (Step 2 of that lifecycle.)
Gets a Call by calling newCall(request) on a factory it holds. (Step 3.)
Fires it with execute() or enqueue(), depending on whether the method returns Call<T> or is suspend. (Step 4.)
Parses the body through your converter factory into UserDto. (Step 5.)

Step 2 is where the interesting design choice lives. To do newCall(request), Retrofit needs something that has a newCall method. In other words, a Call.Factory. And Retrofit stores exactly that, as the interface type:

// Simplified from retrofit2.Retrofit
class Retrofit {
    val callFactory: okhttp3.Call.Factory
    // ...
}

Notice the type. It is not OkHttpClient. It is Call.Factory.

"Retrofit depends on the interface, not the concrete client"

That phrase gets thrown around, and it is worth unpacking precisely. Retrofit's field is typed Call.Factory. Ask what Retrofit actually needs from the client, and the answer is: only the ability to turn a Request into a Call. Retrofit never reads the client's .cache(), .dispatcher(), .connectionPool(), or its timeouts. Its entire per-request interaction with the client is one line:

val call: Call = callFactory.newCall(request)

Typing the field as OkHttpClient would demand more than Retrofit actually uses. Typing it as Call.Factory, the smallest interface that provides newCall, means Retrofit accepts any implementation. The real OkHttpClient, a custom class you wrote, a test double, a lambda. This is dependency inversion in one line: depend on the capability (newCall), not on the class that happens to provide it. And that openness is exactly what makes the .callFactory(...) hook meaningful. You are allowed to substitute your own implementation.

`.client()` is sugar for `.callFactory()`

Here is the reveal that makes everything else click. Look at Retrofit's builder in the current source:

// From retrofit2.Retrofit.Builder, actual code, not simplified

public Builder client(OkHttpClient client) {
    return callFactory(Objects.requireNonNull(client, "client == null"));
}

public Builder callFactory(okhttp3.Call.Factory factory) {
    this.callFactory = Objects.requireNonNull(factory, "factory == null");
    return this;
}

.client(okHttpClient) is pure sugar. It works because OkHttpClient is a Call.Factory, so Retrofit drops it straight into the callFactory field. There is no separate "client path" inside Retrofit. Everything funnels to that one field. If you supply neither, build() fabricates a default:

okhttp3.Call.Factory callFactory = this.callFactory;
if (callFactory == null) {
    callFactory = new OkHttpClient();
}

Three ways in, one field, one method eventually invoked:

You wrote	`callFactory` holds	Per request, Retrofit runs
nothing	a default `OkHttpClient()`	`defaultClient.newCall(request)`
`.client(myClient)`	your `OkHttpClient`	`myClient.newCall(request)`
`.callFactory(f)`	whatever `f` is	`f.newCall(request)`

Every row terminates in something.newCall(request). That is the same call you wrote by hand at Step 3 of the lifecycle in Sending a request without Retrofit. Retrofit is doing that step for you on every method call. .callFactory(...) is you choosing which factory it uses.

The two builds below are behaviorally identical:

// A: the sugar
Retrofit.Builder()
    .baseUrl(BASE_URL)
    .client(okHttpClient)
    .build()

// B: the same thing, longhand. The lambda is a pass-through that adds nothing.
Retrofit.Builder()
    .baseUrl(BASE_URL)
    .callFactory { request -> okHttpClient.newCall(request) }
    .build()

.client(x) is .callFactory { x.newCall(it) } with nothing in the middle. So why would you ever write form B? Because the lambda is a hook. It is a line of your own code that runs at the moment each Call is created. That one line, executed per outgoing request, is what the three use cases below exploit.

What you can do in the hook

Use case 1: defer the cost of building the client

Building an OkHttpClient with a disk Cache touches the filesystem. Filesystem I/O is work you probably do not want on your app-startup critical path. But Retrofit is often built eagerly in a DI graph at startup, and .client(x) demands a fully-built client right then.

The hook lets you defer building the client until the first request actually fires:

// The client is NOT built here. lazy {} only stores the recipe.
val lazyClient = lazy {
    OkHttpClient.Builder()
        .cache(Cache(cacheDir, MAX_CACHE_SIZE))   // disk I/O we want off the startup path
        .addInterceptor(authInterceptor)
        .build()
}

val retrofit = Retrofit.Builder()
    .baseUrl(BASE_URL)
    .callFactory { request ->
        // .value runs the recipe the first time a request fires,
        // then caches the client forever.
        lazyClient.value.newCall(request)
    }
    .addConverterFactory(...)
    .build()

The timing shift is where the win comes from:

.client(okHttpClient)         build client → build Retrofit → (later) first request
                              ▲ disk cache opens at STARTUP

.callFactory { lazy.value }   build Retrofit → (later) first request → build client HERE
                                                                      ▲ disk cache opens on first use

Same field on Retrofit, same eventual newCall(request). Only when the expensive object is constructed moves. The hook is what let it move.

Use case 2: use different clients for different requests

This is the strongest justification for callFactory existing at all, and it is worth spending the most time on.

Some request-level concerns are actually client-level properties in OkHttp. Timeouts are the clearest example. readTimeout, writeTimeout, connectTimeout, and callTimeout are all set on OkHttpClient.Builder. They are baked into the client at construction time.

That leads to a very common problem. Suppose you have one endpoint that runs an on-demand report and reliably takes ninety seconds to respond. Every other endpoint in the app responds in under a second, and you have set a 10-second read timeout on your main client to catch stuck requests early. The report endpoint will always time out.

You cannot solve this with an interceptor. An interceptor runs inside the client. It has access to the request and the response. It does not have access to the timeouts of the client hosting it, and even if it did, changing them mid-chain would not be safe. The property lives one level above where the interceptor executes.

What you need is to pick a different client instance for that one call. That is exactly what the hook is for.

Step 1: create two client instances. Use newBuilder() so that the second client shares the connection pool, dispatcher, and cache with the first. This matters. A fresh OkHttpClient.Builder().build() would create a second, independent connection pool and thread pool, which is wasteful and defeats the point of OkHttpClient being a heavy singleton.

val baseClient = OkHttpClient.Builder()
    .readTimeout(10, TimeUnit.SECONDS)
    .addInterceptor(authInterceptor)
    .build()

// newBuilder() clones the config but SHARES the underlying resources.
// This is a config variant, not a second HTTP stack.
val longRunningClient = baseClient.newBuilder()
    .readTimeout(120, TimeUnit.SECONDS)
    .build()

Step 2: mark the endpoint that needs the second client. Retrofit's @Tag parameter annotation attaches an object to the underlying OkHttp Request as a tag. That tag is later readable via request.tag(SomeClass::class.java), which is exactly what the hook can inspect. Define a marker singleton and take a parameter of that type on the endpoint:

// A marker singleton, used only as a request tag.
object LongRunning

interface ReportApi {
    @GET("reports/{id}/export")
    suspend fun exportReport(
        @Path("id") id: String,
        @Tag marker: LongRunning = LongRunning   // default so callers do not pass it
    ): ReportDto
}

@Tag is a parameter annotation on Retrofit interfaces.

Step 3: in the hook, inspect the tag and pick the right client.

val retrofit = Retrofit.Builder()
    .baseUrl(BASE_URL)
    .callFactory { request ->
        val client = if (request.tag(LongRunning::class.java) != null) {
            longRunningClient
        } else {
            baseClient
        }
        client.newCall(request)
    }
    .build()

Every request that flows through exportReport now gets the 120-second timeout client. Every other request keeps the 10-second timeout. Both share the same connection pool underneath.

This pattern generalises well. The client variant can differ in anything that lives on OkHttpClient.Builder, not just timeouts. A different event listener for a specific set of endpoints, a different SSL configuration for a legacy backend, a different socket factory for a niche transport case. The mechanism is always the same: a marker tag on the request, a branch in the hook, a newCall on the chosen client.

This is the use case an interceptor structurally cannot cover. It is where callFactory earns its place in the API.

Use case 3: rewriting the request before it becomes a `Call`

This one is included for completeness because you will see it in the wild, not because it is the recommended pattern. In the hook, you have the Request in your hand. You can rewrite it before handing it to the client:

val retrofit = Retrofit.Builder()
    .baseUrl(BASE_URL)
    .callFactory { request ->
        val rewritten = request.newBuilder()
            .url(rewriteHost(request.url))   // route to a regional host at runtime
            .build()
        client.newCall(rewritten)
    }
    .build()

This works. It also almost always belongs in an interceptor instead. The next section is about why.

`callFactory` vs interceptors

Both callFactory and interceptors let you touch a request on its way out, so they look interchangeable. They are not. The decisive difference is where in the lifecycle each one runs:

callFactory hook           interceptor chain
       │                          │
  BEFORE a Call exists       INSIDE a Call, during execution
  runs ONCE per call         app interceptor: once per call
                             network interceptor: once PER network request
                                                  (each redirect, each retry)

The fuller picture:

Capability	`Call.Factory` hook	Application interceptor	Network interceptor
Runs	once, before the `Call` exists	once per `Call`	once per network request
Sees redirects and retries	no	no	yes, fires again on each
Can retry or short-circuit	no	yes	yes
Can read/rewrite headers and URL	yes	yes	yes
Can swap client-level config (timeouts, pool)	yes	no	no
Can choose which client instance runs the call	yes	no	no
Access to the served `Response`	no	yes	yes

Read the table as two columns of "only here":

Use an interceptor when the job concerns the request or response content or flow: adding auth headers, logging, retrying on 401, caching decisions, rewriting URLs or headers, short-circuiting with a canned response. Interceptors are strictly more capable for these. They can see the response, they can retry, they can short-circuit. callFactory can do none of those. Request mutation (Use case 3 above) belongs here, not in the factory.

Use callFactory only when the job is structurally impossible for an interceptor because it concerns the client object itself, not the request flowing through it:

Deferring client construction (Use case 1). An interceptor cannot defer building the very client it lives inside.
Choosing which client instance handles the call (Use case 2). Timeouts, socket factories, and pools are client properties. An interceptor runs inside one fixed client and cannot switch to another.

The one-line rule: callFactory is a strictly weaker hook than an interceptor for anything to do with request or response content, so reach for it only for the things an interceptor cannot do. If you see callFactory used just to add a header or log a URL, an interceptor would have been the cleaner choice.

Summary

OkHttpClient, Request, Call, and Response carry the whole OkHttp model. Request is inert data. Call is a Request bound to an OkHttpClient, ready to fire.
Call exists as an object because cancellation and in-flight inspection need a handle that is neither a Request (no engine) nor a Response (already over).
Call.Factory is a one-method fun interface whose whole contract is newCall(request): Call. OkHttpClient implements it. When you wrote client.newCall(request), you were already calling into Call.Factory.
Retrofit's field is typed Call.Factory, not OkHttpClient. It only ever calls newCall. That is why Retrofit accepts any implementation, including a lambda.
.client(x) is a one-line forwarder to .callFactory(x). Same field. The lambda form of .callFactory { ... } is a hook where your own code runs on every outgoing Call.
Reserve callFactory for the things interceptors cannot do: deferring client construction, and choosing which client instance runs the request. Everything else about the request or response belongs in an interceptor.

Handling Empty Response Bodies in Retrofit with a Null-on-Empty Converter Factory

Anubhav — Wed, 29 Jul 2026 16:41:24 +0000

Retrofit makes HTTP calls on Android feel almost effortless. You define an interface, annotate the methods, plug in a converter, and it takes care of the rest. But one of the situations where this smooth pipeline can break is when your server returns an empty response body. Your JSON converter throws a parsing exception and your app crashes.

In this article, we will look at why this happens, what Retrofit already handles for you, and how to build a small custom converter factory (called NullOnEmptyConverterFactory by convention) that fixes the problem cleanly across your entire API.

The Error You Will Actually See

Suppose you have a Retrofit interface that is declared to return a User object after creating a new account:

@POST("users")
suspend fun createUser(@Body request: CreateUserRequest): User

The server acknowledges the creation with a 201 Created, but sends no body back. When your code runs, you see this in Logcat:

java.io.EOFException: End of input at line 1 column 1 path $
    at com.google.gson.stream.JsonReader.nextNonWhitespace(JsonReader.java:1414)
    at com.google.gson.stream.JsonReader.peek(JsonReader.java:429)
    at retrofit2.converter.gson.GsonResponseBodyConverter.convert(GsonResponseBodyConverter.java:33)
    at retrofit2.OkHttpCall.parseResponse(OkHttpCall.java:154)
    ...

Gson (or whichever JSON converter you use) is trying to parse the empty stream, sees no content, and reports it as malformed JSON. The crash is confusing because the network call itself succeeded. It is the deserialization step that failed.

Why This Happens, and Why Only Sometimes

One detail worth pausing on is that Retrofit does handle empty responses, but only for two specific HTTP status codes: 204 No Content and 205 Reset Content. To see why, here is a simplified sketch of what Retrofit does internally when a response arrives:

// Simplified sketch of what Retrofit does in OkHttpCall.parseResponse
Response<T> parseResponse(okhttp3.Response rawResponse) {
    int code = rawResponse.code();

    // Empty-body status codes short-circuit here
    if (code == 204 || code == 205) {
        return Response.success(null, rawResponse);
    }

    // Every other status code goes through the converter chain
    T body = responseConverter.convert(rawResponse.body());
    return Response.success(body, rawResponse);
}

For 204 and 205, Retrofit returns null for the body immediately, without ever calling your converter. The problem shows up when a server returns an empty body under a different status code, most commonly 200 OK or 201 Created. In those cases, Retrofit assumes there is content to parse, hands the stream to your converter, and the converter fails.

Strictly speaking, a server should return 204 when there is no content, but in practice many APIs return 200 or 201 with an empty body. You either need to accept that reality and handle it on the client, or push a fix upstream. Since you often cannot change the backend, we need a client-side solution.

A Quick Refresher on `Converter.Factory`

Before writing the fix, it helps to recall how Retrofit picks a converter. When you call addConverterFactory(...) on the builder, you are adding to an ordered list. For each response type, Retrofit walks that list from top to bottom, asking each factory whether it can produce a Converter for the given type. The first factory that returns a non-null converter wins.

That ordering is what makes the null-on-empty pattern work. If we register our own factory before the JSON converter, we get first crack at every response. We can then decide whether to short-circuit (when the body is empty) or delegate to the JSON converter (when it is not).

This is a straightforward application of the decorator pattern to Retrofit's converter chain.

The Implementation

Here is the Kotlin implementation:

class NullOnEmptyConverterFactory : Converter.Factory() {

    override fun responseBodyConverter(
        type: Type,
        annotations: Array<Annotation>,
        retrofit: Retrofit
    ): Converter<ResponseBody, *> {
        val delegate: Converter<ResponseBody, Any> =
            retrofit.nextResponseBodyConverter(this, type, annotations)

        return Converter<ResponseBody, Any?> { body ->
            if (body.contentLength() == 0L) null else delegate.convert(body)
        }
    }
}

The Java equivalent, for teams still on Java:

public final class NullOnEmptyConverterFactory extends Converter.Factory {

    @Override
    public Converter<ResponseBody, ?> responseBodyConverter(
            Type type,
            Annotation[] annotations,
            Retrofit retrofit) {

        final Converter<ResponseBody, ?> delegate =
                retrofit.nextResponseBodyConverter(this, type, annotations);

        return body -> body.contentLength() == 0 ? null : delegate.convert(body);
    }
}

And here is how you wire it into your Retrofit instance:

val retrofit = Retrofit.Builder()
    .baseUrl("https://api.example.com/")
    .addConverterFactory(NullOnEmptyConverterFactory())
    .addConverterFactory(GsonConverterFactory.create())
    .build()

Notice that NullOnEmptyConverterFactory is registered first. This is not optional. If Gson comes first, it will claim every type and our factory will never be reached.

How It Works, Step by Step

Let us trace what happens when a response comes in.

Retrofit receives the HTTP response and enters parseResponse.
If the status code is 204 or 205, Retrofit returns null without consulting the converter chain at all.
For any other status code, Retrofit needs a Converter<ResponseBody, T> to translate the body into the declared return type. It walks the registered factories in order.
Our NullOnEmptyConverterFactory sits at the front of the list, so Retrofit asks it first.
Inside our factory, we call retrofit.nextResponseBodyConverter(this, type, annotations). The first argument, this, fills Retrofit's skipPast parameter. It tells Retrofit to look for the next factory that can handle this type, skipping ourselves.

To see why this argument matters, imagine we passed null instead. Retrofit's nextResponseBodyConverter would start iterating the factory list from the beginning, find our NullOnEmptyConverterFactory again, and call its responseBodyConverter method. That method would call nextResponseBodyConverter(null, ...) once more, which would find us yet again, and so on. The call stack would look roughly like this:

   NullOnEmptyConverterFactory.responseBodyConverter
     -> Retrofit.nextResponseBodyConverter(skipPast = null)
       -> NullOnEmptyConverterFactory.responseBodyConverter
         -> Retrofit.nextResponseBodyConverter(skipPast = null)
           -> ... (repeats until StackOverflowError)

Passing this as skipPast breaks the cycle. Retrofit skips over our factory during the lookup and moves on to the next one in the chain.

The lookup lands on the next matching factory, which in a typical setup is the Kotlinx Serialization (or Moshi, Gson, Jackson, etc.) converter. That becomes our delegate.
We return a small wrapping converter. When Retrofit invokes it with the response body, we check body.contentLength(). If it is zero, we return null and the JSON converter is never called. If it is non-zero, we hand the body to the delegate and let it do its normal work.

The net effect is that empty bodies produce a clean null value, and non-empty bodies flow through exactly as before.

Pitfalls to Watch Out For

The pattern is simple, but there are a few details that catch people out.

1. Your Return Type Must Be Nullable

If your factory returns null but your Retrofit interface declares a non-null return type, you will still get a crash, just farther down the pipeline. Make sure your interface reflects the reality that the body might be absent:

// Kotlin coroutines
@POST("users")
suspend fun createUser(@Body request: CreateUserRequest): User?

// Kotlin with Call
@POST("users")
fun createUser(@Body request: CreateUserRequest): Call<User?>

For Java, you rely on the fact that Response<T>.body() is already annotated @Nullable, so you just need to check for null at the call site.

2. `contentLength() == 0` Is Not a Perfect Check

ResponseBody.contentLength() returns the value of the Content-Length header when it is present, and -1 when it is not. Servers using chunked transfer encoding often omit the header, so an empty chunked response returns -1, and our simple check misses it.

For most real-world REST APIs, contentLength() == 0L is enough. If you know your server uses chunked encoding for some endpoints, you can peek at the underlying stream to be more thorough. Retrofit response bodies use Okio under the hood, a small I/O library from Square that OkHttp uses for all its byte-level work. You can think of it as a friendlier, more efficient alternative to Java's InputStream and OutputStream. Calling body.source() gives us an Okio BufferedSource, which is essentially a stream with a smart buffer in front of it, and we can peek into that buffer before deciding whether to delegate:

return Converter<ResponseBody, Any?> { body ->
    if (body.contentLength() == 0L) return@Converter null

    val source = body.source()
    source.request(1)
    if (source.buffer.size == 0L) null else delegate.convert(body)
}

Here, source.request(1) asks Okio to try to read at least one byte into the buffer. If nothing arrives, the body is effectively empty. The peeked byte remains in the buffer, so the delegate can still read the full stream normally when we do call it

3. Registration Order Is Not Negotiable

I said this above, but it is worth repeating because it is a frequent source of confusion when this pattern seems not to work. Retrofit does not reorder factories by specificity. It walks them in the exact order you register them, and the first one that claims a type wins. NullOnEmptyConverterFactory must come before the JSON converter, always.

4. The Body Can Only Be Read Once

ResponseBody wraps a network stream that is consumed on read. Our contentLength() check reads header metadata, so it does not touch the stream. If you go with the defensive source.request(1) version, Okio buffers the peeked byte, so the delegate can still consume the body without missing anything. Either version is safe.

When Not to Use This Factory

The null-on-empty factory is a broad, cross-cutting fix. There are situations where a narrower solution reads better.

The endpoint always returns no content. If a specific endpoint is documented to never return a body, declare it as Call<Unit> in Kotlin or Call<Void> in Java. Retrofit already treats these types specially and does not invoke a JSON converter for them. This is more expressive than reaching for the null-on-empty pattern.
You can fix the backend. If the server is under your control and it is returning 200 with an empty body when it means "no content," changing it to 204 is the correct HTTP behavior and eliminates the need for this workaround entirely.

Reach for NullOnEmptyConverterFactory when the same endpoint can genuinely return either a populated body or an empty one, or when many endpoints across your API might occasionally return empty bodies and you want a single, uniform fix.

Summary

The null-on-empty converter factory solves a specific but very common problem: JSON converters crash on empty response bodies when the status code is not 204 or 205. The key takeaways are:

Retrofit already handles 204 and 205 internally by returning null without invoking the converter. The problem is limited to other status codes like 200 and 201 that arrive with an empty body.
The fix is a small Converter.Factory that registers before your JSON converter, delegates to the next factory in the chain, and short-circuits to null when the body is empty.
The call retrofit.nextResponseBodyConverter(this, type, annotations) fetches the delegate. The first argument tells Retrofit to skip past our own factory during that lookup, which is what prevents infinite recursion.
For the pattern to actually surface null to your code, your Retrofit interface must declare nullable return types.
Registration order is critical: NullOnEmptyConverterFactory must come first, before Gson, Moshi, or any other JSON converter factory.

With those pieces in place, your networking layer becomes resilient to a whole class of real-world server behavior that Retrofit does not handle out of the box, with less than twenty lines of code.

The Honour System Running Your Phone's Speaker

Anubhav — Fri, 19 Jun 2026 02:33:26 +0000

Part one of a short series on who actually controls the audio coming out of your Android phone, and why almost none of it is the app you think.

A few days ago I was listening to music on my phone when I opened an unrelated app, one built around an endless feed. The very first screen autoplayed a short video. My music stopped. Not paused and then resumed, not lowered for a moment under the clip. It simply stopped, and I had to go back and press play again.

This is the kind of thing that is easy to never think about. It happens constantly. But this time it nagged at me, because the app that silenced my music was not a media app. It had no obvious business being in charge of my audio. And yet a five-second clip I never asked to watch reached across the system and shut down a dedicated music player. I wanted to understand how a random app gets that power, and whether it is even power at all.

One speaker and a dozen claimants

At any given moment, there is usually exactly one stream of sound that I actually care about, but there are dozens of apps installed, any number of which might want to make noise at the same time. Two apps deciding to play audio at once is not some rare edge case. It is the ordinary condition of a phone. A navigation prompt needs to talk over a podcast. A video call wants the channel a song is currently using. A game wants to play effects while a streaming app sits paused in the background.

So someone, somewhere, has to arbitrate. The question that would not leave me alone was where that arbitration lives and what shape it takes. Is there a single authority that hands out the speaker like a token? Does the loudest or newest app simply win? My instinct said this had to be a system-level concern, because no single app can see what every other app is doing. But the thing I had actually watched happen, a non-media app casually overruling a media app, hinted that the rules were stranger than a tidy priority list.

The system asks, it does not take

The piece I had been missing has a name: audio focus. Once I started thinking in those terms, the behaviour stopped looking like a hostile takeover and started looking like something far more polite, almost to a fault.

My understanding is that an app does not seize the speaker. It asks for it. When an app wants to play sound, the well-behaved thing to do is request audio focus from the system through AudioManager, the per-app gateway into Android's audio service. The system tracks who currently holds focus, conceptually a stack of requests, and when a new app asks, the previous holder is told it has lost focus. Here is the part that reframed everything for me: nobody forces the previous app to go quiet. The system taps it on the shoulder and informs it that someone else has asked to play. What happens next is left entirely to the app that was interrupted.

So my music was never shut down by force. The player that was running received a message saying it had lost focus, and its own code decided to pause. The autoplay video did not reach into the music player and stop it. It asked the system for the floor, and the music player chose to yield.

The vocabulary of an interruption

What convinced me this was deliberate design rather than a lucky accident is the vocabulary the system uses for losing focus. It is not a single off switch. When an app loses focus, it is told roughly how it lost it, and the names of those signals read like a small grammar of courtesy.

private val focusListener = AudioManager.OnAudioFocusChangeListener { change ->
    when (change) {
        AudioManager.AUDIOFOCUS_LOSS ->
            player.pause()        // someone took the floor indefinitely

        AudioManager.AUDIOFOCUS_LOSS_TRANSIENT ->
            player.pause()        // a brief interruption, focus should return

        AudioManager.AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK ->
            player.lowerVolume()  // keep playing, just step aside quietly

        AudioManager.AUDIOFOCUS_GAIN ->
            player.resume()       // the floor is yours again
    }
}

Reading that list told me more about the intent than any specification could. AUDIOFOCUS_LOSS is a permanent goodbye: another app has taken the floor and does not expect to hand it back soon, so the correct response is to stop and let go. AUDIOFOCUS_LOSS_TRANSIENT is a short interruption, the kind an incoming call or a navigation prompt creates, with the expectation that focus returns shortly. And then there is the one I find most telling, AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK, which does not ask the music to stop at all. It asks it to drop its volume and keep playing underneath, the way Maps quiets your music to a murmur while it tells you to turn left, then lets it rise again afterward.

This is why my music stopped outright instead of ducking or pausing and resuming. My guess is that the autoplay video requested a full, indefinite gain, which handed my music player an AUDIOFOCUS_LOSS, the permanent kind. The player did the right thing for a permanent loss. It stopped, and it did not attempt to resume on its own. Compare that to a phone call, which requests transient focus, hands the music a transient loss, and lets it resume the instant the call ends. The same machinery, a different degree of politeness, and you feel the difference as a user without ever needing the words for it.

What makes this almost funny is that I doubt anyone at the company behind that feed app consciously decided to interrupt my music. If their video player is built on one of the common media libraries, requesting audio focus is often the default. Somewhere deep in the stack, a sensible library made a reasonable assumption about how media should behave, and that assumption was enough to stop my music.

An honour system, with everything that implies

The detail I keep turning over is that this whole arrangement runs on trust. Audio focus is advisory. The system can tell an app it has lost focus, but through this mechanism alone it cannot force the app to actually fall silent. A lazily written app can simply ignore the loss and keep playing, and you are left with two streams wrestling over your ears. Most of us have met that app.

So why would the designers choose a cooperative model over a strict one, where the system rips audio away from whoever was holding it? My guess is that the strict version is quietly worse. A forced handover would mean the system decides, for every app, what losing audio ought to mean. Should the sound stop, or pause, or duck? Only the app that was playing knows whether it is a podcast that must pause precisely so you do not miss a sentence, or an ambient track that should simply fade. By making the loss a message rather than a command, the system hands that decision to the one party with enough context to get it right. The cost is plain: it only works when apps cooperate. The reward is that, when they do, the result is far more humane than any central rule could manage.

The floor underneath the floor

What I find quietly strange is that the speaker on a device I own runs almost entirely on an honour system. The app playing my music was never truly in control of whether it kept playing. It was just the most recent voice in a polite, system-wide conversation about who gets the floor, and it stepped back the moment it was asked.

But this only explains why one sound stops when another starts. It says nothing about the moments when sounds do not stop at all: a notification chiming cleanly over the top of a song, an alarm and music sounding in the very same instant. If audio focus were the entire story, those moments should not be possible. Which means the floor I have been describing is not really one floor, and something beneath it is doing work I have not yet accounted for. That is where I want to look next.

DEV Community: Anubhav

Retrofit's `callFactory`: What `.client(okHttpClient)` Is really doing

The four types that carry the whole model

Sending a request without Retrofit

Why Call exists as an object

Call.Factory: the formal name for what you have been doing

Why fun interface matters

What Retrofit actually needs from OkHttp

"Retrofit depends on the interface, not the concrete client"

.client() is sugar for .callFactory()

What you can do in the hook

Use case 1: defer the cost of building the client

Use case 2: use different clients for different requests

Use case 3: rewriting the request before it becomes a Call

callFactory vs interceptors

Summary

Handling Empty Response Bodies in Retrofit with a Null-on-Empty Converter Factory

The Error You Will Actually See

Why This Happens, and Why Only Sometimes

A Quick Refresher on Converter.Factory

The Implementation

How It Works, Step by Step

Pitfalls to Watch Out For

1. Your Return Type Must Be Nullable

2. contentLength() == 0 Is Not a Perfect Check

3. Registration Order Is Not Negotiable

4. The Body Can Only Be Read Once

When Not to Use This Factory

Summary

The Honour System Running Your Phone's Speaker

One speaker and a dozen claimants

The system asks, it does not take

The vocabulary of an interruption

An honour system, with everything that implies

The floor underneath the floor

Why `Call` exists as an object

`Call.Factory`: the formal name for what you have been doing

Why `fun interface` matters

`.client()` is sugar for `.callFactory()`

Use case 3: rewriting the request before it becomes a `Call`

`callFactory` vs interceptors

A Quick Refresher on `Converter.Factory`

2. `contentLength() == 0` Is Not a Perfect Check