Rate Limiting Pattern in Microservices

 Window 12:00-12:01          Window 12:01-12:02
|--------------------------|--------------------------|
                      100 requests | 100 requests
                       at 12:00:59 | at 12:01:01
                     <- 200 requests in 2 seconds ->

package com.example.ratelimit;

import java.time.Duration;

public class TokenBucket {

    private final long capacity;          // maximum burst size
    private final double tokensPerNano;   // refill speed
    private double availableTokens;
    private long lastRefillTime;

    public TokenBucket(long capacity, long refillTokens, Duration refillPeriod) {
        this.capacity = capacity;
        this.tokensPerNano = (double) refillTokens / refillPeriod.toNanos();
        this.availableTokens = capacity;
        this.lastRefillTime = System.nanoTime();
    }

    public synchronized boolean tryConsume() {
        refill();
        if (availableTokens >= 1) {
            availableTokens -= 1;
            return true;    // request allowed
        }
        return false;       // bucket empty: reject
    }

    private void refill() {
        long now = System.nanoTime();
        double newTokens = (now - lastRefillTime) * tokensPerNano;
        availableTokens = Math.min(capacity, availableTokens + newTokens);
        lastRefillTime = now;
    }
}

// 100 requests per minute, with bursts of up to 100
TokenBucket bucket = new TokenBucket(100, 100, Duration.ofMinutes(1));

if (bucket.tryConsume()) {
    // handle the request
} else {
    // respond with 429 Too Many Requests
}

estimated = previousCount x (1 - elapsedInCurrentWindow / windowLength)
          + currentCount

Example: limit 100/minute, 15 seconds into the current minute
  previousCount = 80, currentCount = 30
  estimated = 80 x (1 - 15/60) + 30 = 60 + 30 = 90  -> allowed

package com.example.ratelimit;

import java.time.Duration;

public class SlidingWindowCounter {

    private final int limit;
    private final long windowMillis;
    private long currentWindowStart;
    private int currentCount;
    private int previousCount;

    public SlidingWindowCounter(int limit, Duration window) {
        this.limit = limit;
        this.windowMillis = window.toMillis();
        this.currentWindowStart = System.currentTimeMillis();
    }

    public synchronized boolean tryAcquire() {
        long now = System.currentTimeMillis();
        long elapsed = now - currentWindowStart;

        if (elapsed >= windowMillis) {
            // Move forward; if more than one full window passed, the previous count is 0
            previousCount = (elapsed < 2 * windowMillis) ? currentCount : 0;
            currentCount = 0;
            currentWindowStart = now - (elapsed % windowMillis);
            elapsed = now - currentWindowStart;
        }

        double previousWeight = 1.0 - (double) elapsed / windowMillis;
        double estimated = previousCount * previousWeight + currentCount;

        if (estimated < limit) {
            currentCount++;
            return true;
        }
        return false;
    }
}

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 30
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1791129600

{
  "error": "too_many_requests",
  "message": "Rate limit of 100 requests per minute exceeded. Try again in 30 seconds."
}

package com.example.product.ratelimit;

import java.io.IOException;
import java.time.Duration;
import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;

import org.springframework.http.HttpStatus;
import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;

import com.example.ratelimit.TokenBucket;

import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;

@Component
public class RateLimitFilter extends OncePerRequestFilter {

    private static final int LIMIT_PER_MINUTE = 100;

    private final Map<String, TokenBucket> buckets = new ConcurrentHashMap<>();

    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                    HttpServletResponse response,
                                    FilterChain chain) throws ServletException, IOException {

        String clientKey = resolveClientKey(request);
        TokenBucket bucket = buckets.computeIfAbsent(clientKey,
                key -> new TokenBucket(LIMIT_PER_MINUTE, LIMIT_PER_MINUTE, Duration.ofMinutes(1)));

        if (bucket.tryConsume()) {
            chain.doFilter(request, response);
            return;
        }

        response.setStatus(HttpStatus.TOO_MANY_REQUESTS.value());
        response.setHeader("Retry-After", "1");
        response.setHeader("X-RateLimit-Limit", String.valueOf(LIMIT_PER_MINUTE));
        response.setContentType("application/json");
        response.getWriter().write(
                "{\"error\":\"too_many_requests\",\"message\":\"Please slow down.\"}");
    }

    // Prefer an API key; fall back to the caller's IP address
    private String resolveClientKey(HttpServletRequest request) {
        String apiKey = request.getHeader("X-API-Key");
        return (apiKey != null) ? "key:" + apiKey : "ip:" + request.getRemoteAddr();
    }

    @Override
    protected boolean shouldNotFilter(HttpServletRequest request) {
        // Never rate limit health checks
        return request.getRequestURI().startsWith("/actuator/health");
    }
}

spring:
  cloud:
    gateway:
      server:
        webflux:
          routes:
            - id: product-service
              uri: lb://product-service
              predicates:
                - Path=/api/products/**
              filters:
                - StripPrefix=1
                - name: RequestRateLimiter
                  args:
                    redis-rate-limiter.replenishRate: 2      # tokens per second (about 120/minute)
                    redis-rate-limiter.burstCapacity: 20     # maximum short burst
                    redis-rate-limiter.requestedTokens: 1    # tokens per request
                    key-resolver: "#{@apiKeyResolver}"

package com.example.gateway.config;

import org.springframework.cloud.gateway.filter.ratelimit.KeyResolver;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import reactor.core.publisher.Mono;

@Configuration
public class RateLimitKeyConfig {

    // One bucket per API key; requests without a key fall back to the IP address
    @Bean
    public KeyResolver apiKeyResolver() {
        return exchange -> {
            String apiKey = exchange.getRequest().getHeaders().getFirst("X-API-Key");
            if (apiKey != null) {
                return Mono.just("key:" + apiKey);
            }
            return Mono.justOrEmpty(exchange.getRequest().getRemoteAddress())
                    .map(address -> "ip:" + address.getAddress().getHostAddress())
                    .defaultIfEmpty("ip:unknown");
        };
    }
}

resilience4j:
  ratelimiter:
    instances:
      currency-api:
        limit-for-period: 10          # 10 calls...
        limit-refresh-period: 1s      # ...per second
        timeout-duration: 200ms       # wait up to 200 ms for permission

package com.example.order.client;

import java.math.BigDecimal;

import org.springframework.stereotype.Component;
import org.springframework.web.client.RestClient;

import io.github.resilience4j.ratelimiter.RequestNotPermitted;
import io.github.resilience4j.ratelimiter.annotation.RateLimiter;

@Component
public class CurrencyClient {

    private final RestClient restClient;
    private final ExchangeRateCache cache;

    public CurrencyClient(RestClient.Builder builder, ExchangeRateCache cache) {
        this.restClient = builder.baseUrl("https://api.currency.example").build();
        this.cache = cache;
    }

    @RateLimiter(name = "currency-api", fallbackMethod = "cachedRate")
    public BigDecimal getRate(String from, String to) {
        BigDecimal rate = restClient.get()
                .uri("/rates?from={from}&to={to}", from, to)
                .retrieve()
                .body(BigDecimal.class);
        cache.put(from, to, rate);
        return rate;
    }

    // Used when our own limit is reached
    private BigDecimal cachedRate(String from, String to, RequestNotPermitted ex) {
        return cache.get(from, to);
    }
}

package com.example.ratelimit;

import java.time.Duration;
import java.time.Instant;

import org.springframework.data.redis.core.StringRedisTemplate;
import org.springframework.stereotype.Component;

@Component
public class RedisRateLimiter {

    private static final int LIMIT = 100;
    private static final Duration WINDOW = Duration.ofMinutes(1);

    private final StringRedisTemplate redis;

    public RedisRateLimiter(StringRedisTemplate redis) {
        this.redis = redis;
    }

    public boolean tryAcquire(String clientKey) {
        // One key per client per minute, for example "rate:key:abc123:29852160"
        long window = Instant.now().getEpochSecond() / WINDOW.toSeconds();
        String redisKey = "rate:" + clientKey + ":" + window;

        // INCR is atomic, so concurrent requests on all instances are counted correctly
        Long count = redis.opsForValue().increment(redisKey);

        if (count != null && count == 1) {
            // First request in this window: let Redis delete the key afterwards
            redis.expire(redisKey, WINDOW.plusSeconds(5));
        }
        return count != null && count <= LIMIT;
    }
}

package com.example.client;

import java.time.Duration;

import org.springframework.web.client.HttpClientErrorException;
import org.springframework.web.client.RestClient;

public class PoliteApiClient {

    private static final int MAX_ATTEMPTS = 3;

    private final RestClient restClient;

    public PoliteApiClient(RestClient restClient) {
        this.restClient = restClient;
    }

    public String getProduct(String productId) throws InterruptedException {
        for (int attempt = 1; ; attempt++) {
            try {
                return restClient.get()
                        .uri("/products/{id}", productId)
                        .retrieve()
                        .body(String.class);
            } catch (HttpClientErrorException.TooManyRequests ex) {
                if (attempt == MAX_ATTEMPTS) {
                    throw ex;
                }
                Thread.sleep(waitTime(ex, attempt).toMillis());
            }
        }
    }

    // Respect Retry-After if present; otherwise back off exponentially: 1s, 2s, 4s...
    private Duration waitTime(HttpClientErrorException ex, int attempt) {
        String retryAfter = ex.getResponseHeaders() != null
                ? ex.getResponseHeaders().getFirst("Retry-After")
                : null;
        if (retryAfter != null && retryAfter.chars().allMatch(Character::isDigit)) {
            return Duration.ofSeconds(Long.parseLong(retryAfter));
        }
        return Duration.ofSeconds(1L << (attempt - 1));
    }
}