DEV Community: Anubhav

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.