API Rate Limiting using Resilience4J & Spring Boot
How API rate limiting works, why fixed windows fail under bursts, and how to implement a sliding-window rate limiter with Resilience4J in Spring Boot, tested with JMeter.

Introduction
In this blog, we’ll dive into the critical concept of API Rate Limiting and see how to implement a robust solution using Resilience4J in a Spring Boot application.
We will cover:
- What API Rate Limiting is.
- How the basic Fixed Window algorithm fails (the bursting issue).
- How the Sliding Window algorithm, used by Resilience4J, solves the problem.
- Implementing and configuring rate limiting in a Spring Boot REST API.
- Testing the solution using JMeter.
What is API Rate Limiting?
API Rate Limiting is a defensive mechanism used to restrict the number of client requests an API will process within a specified time duration.
For example, a typical policy might allow 5 requests per every 10 seconds from a single user. Any requests that exceed this threshold are instantly rejected with an HTTP 429 Too Many Requests status code.
This practice is essential for:
- System Stability: Preventing sudden spikes of traffic from overwhelming your backend services.
- Abuse Prevention: Protecting against Distributed Denial of Service (DDoS) attacks.
- Fair Usage: Ensuring all consumers get a consistent quality of service.
Fixed Window vs. Sliding Window
Understanding the algorithm is key to effective rate limiting.
The Fixed Window Issue
The Fixed Window algorithm is the simplest approach. It divides the timeline into fixed, non-overlapping intervals (e.g., 60 seconds). All requests within that interval count toward the limit.
The major flaw is the “blasting” or “edge-case” problem.
| Time | Action | Result |
|---|---|---|
| Window 1 (Second 59) | User sends 5 requests (Limit is 5 per 60s) | Processed. |
| Window 2 (Second 01) | User sends 5 more requests | Processed, as the limit just reset. |
In this scenario, your API processed 10 requests in a span of just two seconds across the boundary. This heavy burst of traffic can still lead to momentary overload, even though the rate limit wasn’t technically violated in either window.
The Sliding Window Solution
The Sliding Window algorithm solves the blasting problem by providing a much smoother enforcement. It works by looking at a rolling window of time.
Instead of fixed buckets, the system maintains a log of timestamps for all successful requests. When a new request arrives, it only considers the requests that occurred within the past window duration (e.g., the last 10 seconds).
- It checks the request count in the immediately preceding time window.
- If the count is less than the limit, the request is processed, and its timestamp is added to the log.
This ensures that the number of requests in any rolling window never exceeds the configured limit, eliminating the boundary spikes. Resilience4J uses this superior algorithm for its rate limiting implementation.
Implementing Rate Limiting in Spring Boot
Let’s put this into practice in a Spring Boot application.
1. Adding Dependencies
We need the core web starter, the Resilience4J library, and the AOP starter to enable the annotation-based configuration.
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>io.github.resilience4j</groupId>
<artifactId>resilience4j-spring-boot3</artifactId>
<version>2.2.0</version> </dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-aop</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
</dependencies>
- Creating a Rate-Limited Endpoint We create a simple REST controller and apply the @RateLimiter annotation. We also include a fallbackMethod to provide a clean response when the limit is reached.
@RestController
@RequestMapping("/api")
public class RateLimitedController {
// Applies the rate limiter configuration named "test-api"
@GetMapping("/hello")
@RateLimiter(name = "test-api", fallbackMethod = "fallbackSayHello")
public String sayHello() {
// Simulating some processing time
return "Hello! Request successfully processed.";
}
// Fallback method executed when the limit is hit
// It accepts a Throwable parameter, which will be the RateLimiter exception
public String fallbackSayHello(Throwable t) {
// The service is protected, return a polite error
return "Too Many Requests! Please try again later. (Error: " + t.getMessage() + ")";
}
}
- Configuring the Rate Limiter The behavior of the test-api instance is defined in application.yml:
resilience4j.ratelimiter:
instances:
test-api:
# Max number of requests allowed in the limit-refresh-period
limit-for-period: 5
# The size of the window (how often the limit resets/refreshes)
limit-refresh-period: 15s
# How long a blocked thread can wait for a token before giving up.
# Setting this to > 0s allows for "waiting" instead of immediate rejection.
timeout-duration: 5s
# Register the rate limiter status in the Actuator health endpoint
register-health-indicator: true
management:
endpoints:
web:
exposure:
include: health, ratelimiters # Expose the ratelimiters endpoint
| Configuration Key | Description |
|---|---|
| limit-for-period | The maximum number of requests allowed per window. |
| limit-refresh-period | The duration of the sliding window. |
| timeout-duration | The maximum time a thread waits to acquire a token before being rejected. |
Testing the Rate Limiter using JMeter
With the application running, we can test our configuration (5 requests per 15 seconds) by simulating a spike in traffic using JMeter or any other load testing tool.
Testing Steps:
-
Thread Group: Configure a Thread Group with the Number of Threads (Users) set to a value significantly higher than the limit (e.g., 50). Set the Ramp-up period to a low value (e.g., 1 second) to ensure all 50 requests hit the server nearly simultaneously.
-
HTTP Request Sampler: Point the request to our endpoint: GET http://localhost:8080/api/hello.
-
Run: Execute the test.
Expected Results:
-
The first 5 requests will be processed successfully, returning the status HTTP 200 OK and the message: “Hello! Request successfully processed.”
-
The remaining 45 requests will be blocked by the rate limiter. Due to our fallbackMethod being executed successfully, they will also return HTTP 200 OK, but with the message: “Too Many Requests! Please try again later. (Error: RateLimiter ’test-api’ does not permit further calls)”
Note: If you removed the fallbackMethod, the blocked requests would return the standard 429 Too Many Requests HTTP status code. The use of the fallback provides a more graceful and user-friendly experience.
Conclusion
Rate limiting is not just an optional feature; it’s a fundamental requirement for building resilient and scalable microservices. By leveraging the Sliding Window algorithm through Resilience4J and Spring Boot’s seamless configuration, you can effectively protect your services from sudden traffic spikes and guarantee a consistent user experience.
Get new articles by email
One short email whenever a new article is published. No spam, unsubscribe anytime.
Comments
No comments yet. Be the first to share your thoughts.