Testing REST API rate limiting with Bucket4j and Spring

Rate limiting is easy to implement and surprisingly difficult to verify. A token-bucket policy can accept a burst, refill over time, and assign separate capacity to tenants, yet tests often collapse into a loop that sleeps for a second. The useful assertion is not simply that the API eventually rejects traffic; it is that every accepted and rejected request matches a declared contract.

A practical approach to testing REST API rate limiting with Bucket4j and Spring combines deterministic clocks, isolated quota state, exact response assertions, and carefully controlled concurrency tests. For teams in Sydney’s fintech sector and Melbourne’s online marketplaces, this matters because a limiter that works in isolation can still leak capacity between customers, mishandle identity boundaries, or produce confusing errors during busy trading and retail periods.

Rate limits as observable contracts

A rate limit is an agreement between a server and its clients. It specifies how much work may occur within a period, which identity receives that allowance, and what happens when the allowance is exhausted. Bucket4j models this with token-bucket behaviour, while a Spring filter, interceptor, or service wrapper applies the policy to an endpoint. The HTTP result then becomes an observable part of the API contract.

The contract should cover more than the 429 Too Many Requests status. It may define Retry-After, remaining quota, reset timing, response bodies, and whether limits apply per user, API key, subscription, or IP address. That symmetry follows a quid pro quo principle: the server promises capacity under stated conditions, and the client agrees to respect the published boundary.

Limit semantics should also reflect the product being served. An Australian checkout API might allow bursts while reading a catalogue but restrict quote creation more tightly. Prices denominated in AUD and GST-inclusive totals may attract different traffic patterns from low-value catalogue requests, so one global quota can conceal an imbalance between read and write operations.

Designing deterministic boundary scenarios

Start with a capacity small enough to exhaust quickly. A bucket allowing five requests is convenient for proving that requests one through five succeed and request six is rejected. Separate scenarios should then cover refill, tenant isolation, reset headers, quota exhaustion during a burst, and recovery after the waiting period. Each scenario needs one clear expectation so a failure identifies the broken rule.

Time is the main source of nondeterminism. Instead of sleeping until a refill occurs, inject a mutable or fixed clock into the bucket construction. The test can then advance time by exactly one refill interval and issue another request. If the Spring integration does not expose clock configuration, wrap bucket creation in a test-controlled provider rather than reaching into private fields or restarting the application context.

Local time deserves attention too. Sydney and Melbourne clocks remain one hour apart and both change for daylight saving, while UTC-based bucket windows remain stable. Tests should use an explicit ZoneId wherever a response exposes a reset timestamp, and they should avoid assuming that local midnight defines the quota window.

Exercising Spring endpoints under test

A Spring Boot integration test can exercise the complete request path, including authentication, controller advice, filters, and the Bucket4j policy. @SpringBootTest with a random port and TestRestTemplate suits a blocking MVC application. A reactive Spring application can use @WebFluxTest and WebTestClient, although asynchronous request handling requires different timing assertions.

Choose the quota identity deliberately. Tests should send the authentication or tenant header used in production rather than relying on an accidental shared localhost identity. This is especially important when the limiter runs before the controller: placing the filter after authentication allows Bucket4j to allocate capacity to the correct customer, while placing it too early may count every request against one anonymous bucket.

A typical rejection assertion can remain straightforward:

ResponseEntity<String> response = restTemplate.exchange(
    "/api/quotes?currency=AUD",
    HttpMethod.GET,
    HttpEntity.EMPTY,
    String.class
);

assertThat(response.getStatusCode())
    .isEqualTo(HttpStatus.TOO_MANY_REQUESTS);

TestRestTemplate normally allows the 429 response to be inspected directly, so an exception assertion is rarely necessary. The test should also examine the body and headers to ensure the Spring exception handler produces the documented client experience.

Comparing state isolation strategies

Several isolation methods are available, but they verify different behaviours. A deterministic unit-style boundary test exposes the policy clearly, while a full HTTP test proves that Spring wires it correctly. Choosing the wrong isolation level can hide shared-state defects or make a fast suite unnecessarily slow.

Approach	State control	Best fit	Main limitation
Bucket created per test	Complete	Policy and refill logic	Does not prove endpoint integration
Shared bucket reset between tests	Explicit reset	MVC integration tests	Reset support may bypass real transitions
Injectable clock	No real waiting	Refill and reset scenarios	Does not test timer scheduling
Separate process or load test	Process isolation	Burst and sustained traffic	Slower and less deterministic

Shared Spring contexts should be reused for speed, but any mutable quota store must be reset or recreated between tests. Otherwise, test execution order can determine which request receives a 429. Conversely, creating a fresh application context for every case may erase useful evidence about shared caches, singleton filters, and improperly stored buckets.

Checking rejection and recovery

A rejection test should assert the status, body shape, and relevant rate-limit metadata together. Header names differ between implementations: some services expose X-RateLimit-Remaining, while others use RateLimit-Remaining. These are not interchangeable by default, so tests must follow the API’s published contract rather than whichever header happens to be convenient.

Timing values need equally careful interpretation. Retry-After can contain a delay in seconds or an HTTP date, depending on the service contract. A test should calculate the expected value from the controlled clock and allow only the precision required by the implementation. It should not assume that the server’s reset header uses epoch seconds, delta seconds, or a midnight boundary.

Recovery testing proves that exhaustion is temporary. After the retry interval, the next request should succeed and the remaining allowance should reflect the refill. With an injected clock, this transition is immediate and exact; with a real scheduler, Awaitility can poll until the expected response appears. Australian operating customs place weight on supportable failure, so a clear error and trustworthy retry guidance should remain consistent even when requests originate from different states.

Handling bursts and asynchronous work

Sequential calls demonstrate a quota boundary, but a token bucket also controls how many requests may arrive together. A concurrency test can start several threads against the same Spring endpoint, coordinate them with a barrier, and count accepted and rejected responses. The expected total accepted count must not exceed the bucket capacity, while every excess request should receive a controlled rejection.

Concurrent clients must share the same identity when testing one bucket. Running parallel requests with different tenant headers verifies isolation rather than contention and can accidentally make a broken implementation appear correct. Bucket4j is designed for concurrent consumption, but the surrounding Spring code must also avoid reading a remaining count and then performing a separate, race-prone update.

Asynchronous endpoints add another dimension. A CompletableFuture may outlive the filter call, while a reactive pipeline may consume quota at a different stage from request arrival. The patterns described in asynchronous Java testing help distinguish the initial HTTP response from later completion. Tests should record when the limiter consumes capacity, when the controller starts, and when background work finishes, ensuring the token is not returned or duplicated incorrectly.

Keeping the checks release-ready

Split the verification into complementary layers. Fast unit tests should cover Bucket4j configuration, consumption decisions, and refill arithmetic. Spring integration tests should prove that identity resolution, filters, exception handling, and header generation work together. A separate load-testing job can then exercise realistic bursts and sustained traffic without making the ordinary CI suite slow or flaky.

Keep quota values configurable for tests, but avoid exposing a production bypass that could accidentally disable protection. Tagged contract tests can verify 429 behaviour, retry metadata, and tenant isolation against a small dedicated endpoint. Their deterministic clocks and bounded request counts also make failures easier to reproduce from CI logs in Australian teams operating across AEDT and AEST support windows.

The next concrete step is to add one fixed-capacity integration test that exhausts its bucket, verifies the 429 response and headers, and advances the injected clock to confirm recovery in CI.