By now, you're comfortable with basic coroutines, but in the real world, you rarely get to just "fire and forget." Most APIs you'll integrate with have strict rate limits. If you hammer a server with 100 requests a second, you'll get a 429 Too Many Requests error, or worse, a temporary IP ban. We need a way to queue those requests and space them out without blocking the underlying threads.

How do I stop my coroutines from hammering an API too fast?

The most intuitive way to start is by creating a wrapper function that forces a minimum gap between calls. Since we're using coroutines, we absolutely cannot use Thread.sleep()—that would kill your performance. Instead, we use delay(). I usually suggest creating a class that manages the timing state so you don't have global variables floating around your project.

class SimpleRateLimiter(private val minIntervalMillis: Long) {
    private var lastRequestTime = 0L

    suspend fun  execute(block: suspend () -> T): T {
        val currentTime = System.currentTimeMillis()
        val timeSinceLast = currentTime - lastRequestTime
        
        if (timeSinceLast < minIntervalMillis) {
            val delayTime = minIntervalMillis - timeSinceLast
            delay(delayTime)
        }
        
        lastRequestTime = System.currentTimeMillis()
        return block()
    }
}

In this setup, if you try to call execute twice in rapid succession, the second call will just suspend until the required interval has passed. It's clean, and it doesn't block the thread, allowing other parts of your app to keep running.

Won't this break if ten different coroutines call the limiter at once?

Yes, it will. The SimpleRateLimiter above is not thread-safe. If two coroutines check lastRequestTime at the exact same millisecond, they'll both think it's okay to proceed, and you've just bypassed your own limit. When you're dealing with shared state across coroutines, you need a synchronization primitive. I prefer a Mutex over a synchronized block because Mutex.withLock is non-blocking—it suspends the coroutine instead of parking the thread.

import kotlinx.coroutines.sync.Mutex
import kotlinx.coroutines.sync.withLock

class ThreadSafeRateLimiter(private val minIntervalMillis: Long) {
    private var lastRequestTime = 0L
    private val mutex = Mutex()

    suspend fun <T> execute(block: suspend () -> T): T {
        mutex.withLock {
            val currentTime = System.currentTimeMillis()
            val timeSinceLast = currentTime - lastRequestTime
            
            if (timeSinceLast < minIntervalMillis) {
                delay(minIntervalMillis - timeSinceLast)
            }
            
            lastRequestTime = System.currentTimeMillis()
        }
        // We call the block OUTSIDE the lock so we don't hold the mutex 
        // while waiting for the actual network response.
        return block()
    }
}

Notice that I moved the block() call outside the withLock. This is a critical detail. If the network call takes two seconds, you don't want to lock the entire limiter for those two seconds; you only want to lock the logic that decides when the call starts.

Is there a way to allow "bursts" of requests instead of a strict gap?

The "minimum interval" approach is a bit rigid. Often, APIs allow you to make, say, 10 requests immediately, as long as you don't exceed 10 requests per second. This is known as the Token Bucket algorithm. In Kotlin, the most elegant way to implement this is using a Channel as a bucket of permits.

I like this approach because it leverages the natural queuing behavior of Channels. You have a separate "refill" coroutine that drops permits into the channel at a set interval, and your requests simply try to take a permit before proceeding.

import kotlinx.coroutines.*
import kotlinx.coroutines.channels.Channel

class TokenBucketLimiter(val maxTokens: Int, val refillRateMillis: Long) {
    private val bucket = Channel<Unit>(maxTokens)

    init {
        // Background worker to refill the bucket
        CoroutineScope(Dispatchers.Default).launch {
            while (isActive) {
                bucket.send(Unit) // Add a token
                delay(refillRateMillis)
            }
        }
    }

    suspend fun <T> execute(block: suspend () -> T): T {
        bucket.receive() // Suspend here until a token is available
        return block()
    }
}

This is much more flexible. If the app has been idle, the bucket fills up to maxTokens, allowing a burst of requests to fly through instantly. Once the bucket is empty, the code naturally slows down to the refillRateMillis. It's a powerful pattern that scales well for complex API integrations.

📋 Practical Task

Exercise: Build a Token-Bucket Rate Limiter for a Social Media Feed API

You are integrating a social media API that allows a burst of 5 requests, but then limits you to 1 request every 200 milliseconds to prevent spamming.

Your Task:

• Implement a SocialMediaRateLimiter class using a Channel based Token Bucket approach.
• The limiter should be initialized with a capacity of 5 tokens and a refill rate of 200ms.
• Create a suspend fun fetchPost(id: Int) that simulates a network call by printing "Fetching post $id" and calling delay(50).
• In a runBlocking block, launch 15 concurrent coroutines that all attempt to call fetchPost through your rate limiter.
• Verify in the console output that the first 5 requests happen almost instantly, and the remaining 10 are spaced out by approximately 200ms.