I remember a project a few years back where we were integrating a legacy banking API. The documentation explicitly stated a limit of "5 requests per second," but it didn't mention how strictly they enforced it. We had a bunch of concurrent Task blocks firing off to populate a dashboard, and within milliseconds, we were hitting 429 "Too Many Requests" errors. The problem wasn't that we were sending too many requests overall, but that we were sending them all at the exact same instant. We needed a way to serialize these requests and force a gap between them, regardless of which part of the app was triggering the call.

This is where an actor becomes your best friend. Because actors guarantee mutually exclusive access to their internal state, they are the perfect mechanism for a rate limiter. You can keep track of when the last request was sent and force the current caller to wait if they're moving too fast. Since the actor handles the synchronization, you don't have to mess around with locks or semaphores, which—let's be honest—is a recipe for deadlocks if you aren't extremely careful.

Synchronizing Request Intervals

The core of a rate limiter is simply tracking a timestamp. When a request comes in, the actor checks the difference between the current time and the last successful request. If the gap is smaller than your allowed threshold, the actor uses Task.sleep to pause the execution. Because the actor processes messages one at a time, subsequent requests will queue up behind the sleeping task, naturally spacing them out.

actor RateLimiter {
    private let minInterval: Duration
    private var lastRequestDate = ContinuousClock.now - minInterval

    init(requestsPerSecond: Double) {
        // Calculate the gap required between requests
        self.minInterval = .seconds(1.0 / requestsPerSecond)
    }

    func execute<T>(operation: () async throws -> T) async rethrows -> T {
        let now = ContinuousClock.now
        let elapsed = now - lastRequestDate
        
        if elapsed < minInterval {
            let delay = minInterval - elapsed
            try await Task.sleep(for: delay)
        }
        
        // Update the timestamp after the potential sleep
        lastRequestDate = ContinuousClock.now
        return try await operation()
    }
}

Avoiding the "Thundering Herd"

One thing I've noticed developers struggle with is the difference between throttling and rate limiting. Throttling usually means "ignore everything until a timer expires." Rate limiting, as we've implemented it here, means "ensure every request eventually happens, but space them out."

By using try await Task.sleep inside the actor, we aren't blocking the underlying thread. The thread is freed up to do other work while the specific task associated with that request is suspended. When the timer hits, the task resumes, updates the lastRequestDate, and finally executes the operation. This ensures that even if you fire 100 requests simultaneously, they will bleed out one by one at exactly the rate you specified, without freezing your UI or crashing your app.

📋 Practical Task

Exercise: Building a Token-Bucket Rate Limiter

In a real-world scenario, a strict "one-by-one" gap is often too rigid. Most APIs use a "Token Bucket" algorithm: you can send a burst of requests (the bucket size), but once the bucket is empty, you must wait for tokens to refill at a steady rate.

Your task is to modify the RateLimiter actor to implement this burst logic. Build a TokenBucketLimiter actor with the following requirements:

• Properties:
  • maxTokens: The maximum number of requests allowed in a burst.
  • refillRate: How many tokens are added back per second.
  • availableTokens: A current count of tokens.
  • lastRefillTime: A timestamp of when the tokens were last updated.
• Logic:
  • Every time execute is called, first calculate how many new tokens should have been added since lastRefillTime based on the refillRate.
  • Add those tokens to availableTokens, capping it at maxTokens.
  • If availableTokens is > 0, decrement a token and execute the operation immediately.
  • If availableTokens is 0, calculate the time remaining until at least one token becomes available, await Task.sleep for that duration, then refill and execute.

Test your implementation by spawning 20 concurrent tasks that attempt to print "Request sent" using the limiter, ensuring the first burst happens instantly and the remainder are spaced out according to your refill rate.