To protect APIs from abuse and ensure fair usage, rate limiting is essential. It prevents users or clients from overwhelming the system by enforcing a limit on how often they can call your APIs. In this guide, you’ll learn how to implement per-user throttling in Java using Spring Boot and Redis, using the token bucket algorithm.

1. Why Use Redis for Rate Limiting?

• Low latency and high throughput
• Atomic operations using Redis scripts (Lua)
• Persistence (optional) and cluster support
• Suitable for distributed systems — state doesn’t live in application memory

2. The Token Bucket Algorithm

The token bucket algorithm is widely used for rate limiting. Here’s how it works:

• Each user has a bucket with tokens.
• Each request consumes one token.
• Tokens are refilled at a fixed rate.
• If there are no tokens, the request is denied or delayed.

This model allows for short bursts while maintaining an average rate.

3. Redis Lua Script for Rate Limiting

-- token_bucket.lua
local key = KEYS[1]
local max_tokens = tonumber(ARGV[1])
local refill_rate = tonumber(ARGV[2])
local now = tonumber(ARGV[3])
local requested = tonumber(ARGV[4])

local bucket = redis.call("HMGET", key, "tokens", "timestamp")
local tokens = tonumber(bucket[1]) or max_tokens
local timestamp = tonumber(bucket[2]) or now

local delta = math.max(0, now - timestamp)
tokens = math.min(max_tokens, tokens + delta * refill_rate)
local allowed = tokens >= requested
if allowed then
 tokens = tokens - requested
end

redis.call("HMSET", key, "tokens", tokens, "timestamp", now)
redis.call("EXPIRE", key, 60)

return allowed

4. Spring Boot Integration

1. Redis Configuration

@Configuration
public class RedisConfig {
 @Bean
 public RedisTemplate<String, String> redisTemplate(RedisConnectionFactory factory) {
 RedisTemplate<String, String> template = new RedisTemplate<>();
 template.setConnectionFactory(factory);
 return template;
 }
}

2. RateLimiter Service

@Service
public class RateLimiterService {

 @Autowired
 private RedisTemplate<String, String> redisTemplate;

 private final DefaultRedisScript<Boolean> rateLimiterScript;

 public RateLimiterService() {
 rateLimiterScript = new DefaultRedisScript<>();
 rateLimiterScript.setScriptSource(new ResourceScriptSource(new ClassPathResource("token_bucket.lua")));
 rateLimiterScript.setResultType(Boolean.class);
 }

 public boolean isAllowed(String userId) {
 String key = "bucket:" + userId;
 List<String> keys = List.of(key);

 Long now = Instant.now().getEpochSecond();
 return Boolean.TRUE.equals(redisTemplate.execute(
 rateLimiterScript,
 keys,
 "10", // max_tokens
 "1", // refill_rate (tokens/sec)
 now.toString(),
 "1" // requested tokens
 ));
 }
}

3. Middleware/Interceptor

@Component
public class RateLimitingInterceptor implements HandlerInterceptor {

 @Autowired
 private RateLimiterService rateLimiterService;

 @Override
 public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
 String userId = request.getHeader("X-User-Id");
 if (userId == null || !rateLimiterService.isAllowed(userId)) {
 response.setStatus(HttpStatus.TOO_MANY_REQUESTS.value());
 return false;
 }
 return true;
 }
}

4. Register the Interceptor

@Configuration
public class WebConfig implements WebMvcConfigurer {
 @Autowired
 private RateLimitingInterceptor rateLimitingInterceptor;

 @Override
 public void addInterceptors(InterceptorRegistry registry) {
 registry.addInterceptor(rateLimitingInterceptor);
 }
}

5. Benefits of This Approach

• ⚙️ Scalable: Stateless, works in distributed environments
• 🧪 Testable: Token bucket logic lives in Redis script
• 🔐 Secure: Per-user rate limiting avoids abuse
• 🕰️ Flexible: Adjust tokens, refill rates per endpoint/user type

6. Optional Enhancements

• Use a different refill rate per API key or user tier
• Implement burst handling via leaky bucket fallback
• Store limits in Redis hashes or config maps
• Expose remaining quota in HTTP headers

7. Conclusion

Rate limiting is critical for building resilient APIs. By combining Spring Boot, Redis, and a token bucket algorithm, you get a robust and scalable per-user rate limiter that supports zero-downtime, distributed environments. Redis handles concurrency and token math, while your app stays clean and fast.