Rate Limiting, Retry, and Time Limiters

Circuit breakers stop calling a dead dependency, but they are only one tool in the resilience toolbox. To shape inbound load and contain cascading failures you combine three more Resilience4j primitives:

• RateLimiter — caps how many calls per time window are allowed to start. Excess callers wait or are rejected.
• Retry — re-invokes a failed call a bounded number of times, ideally with backoff, to ride out transient errors.
• TimeLimiter — caps how long a single call may run before it is cancelled, freeing the thread and bounding tail latency.

Used together they protect both you (don't overload your own service) and your downstream (don't hammer a struggling dependency).

Spring Boot 4 integrates Resilience4j through the Spring Cloud Circuit Breaker / resilience4j-spring-boot3 starter, which exposes annotation-driven aspects for every primitive.

Add the starter and AOP support so the annotations are woven in:

• resilience4j-spring-boot3 brings RateLimiter, Retry, TimeLimiter, CircuitBreaker, and Bulkhead aspects.
• spring-boot-starter-aop is required — the annotations are implemented as AOP advice.
• Metrics flow into Micrometer automatically when Actuator is present.

A RateLimiter divides time into refresh periods. Each period grants a fixed number of permits. A caller that finds no permit available waits up to timeoutDuration; if still none, it fails fast with RequestNotPermitted.

Configure instances in application.yml under resilience4j.ratelimiter:

• limitForPeriod — permits granted each refresh period.
• limitRefreshPeriod — how often the permit count resets.
• timeoutDuration — how long a caller blocks waiting for a permit before being rejected.

Annotate the method that calls the protected resource. The name must match the YAML instance. When the limit is exceeded and no permit frees up within timeoutDuration, Resilience4j throws RequestNotPermitted — route it to a fallback so clients get a graceful 429 instead of a stack trace.

Key decision: a RateLimiter throttles your outbound calls. It does not slow down inbound HTTP traffic by itself — pair it with a fallback that signals back-pressure.

A Retry re-invokes a failed call up to maxAttempts times. It is only correct for transient faults — connection resets, 503s, brief timeouts — and only safe on idempotent operations. Retrying a non-idempotent POST can double-charge a customer.

Use exponential backoff to avoid synchronized retry storms, and be explicit about which exceptions retry vs. which abort immediately:

• retryExceptions — only these trigger a retry.
• ignoreExceptions — these abort instantly (e.g. 4xx client errors).
• enableExponentialBackoff with a multiplier spreads attempts out.

Exponential backoff multiplies the wait after each attempt: 200ms, 400ms, 800ms... But if thousands of clients fail at the same instant, they all back off in lock-step and re-converge — a retry storm. Adding jitter (randomized wait) de-synchronizes them.

This standalone program models the wait schedule so you can see the spread of backoff-with-jitter delays an online judge can run with no framework:

Stack @Retry on the same method. Order matters when annotations combine: Resilience4j applies aspects in the order Retry → CircuitBreaker → RateLimiter → TimeLimiter → Bulkhead (outermost to innermost), so a retry wraps the rate-limited call and each attempt re-acquires a permit.

The fallback receives the final exception after all attempts are exhausted:

A TimeLimiter caps how long a single asynchronous call may run. It only works with futures — the method must return CompletableFuture (or another supported async type) so Resilience4j can cancel it when the deadline passes.

This is the antidote to slow dependencies: a retry handles failures, but a call that simply hangs for 30 seconds will exhaust your thread pool. The TimeLimiter converts a hang into a fast TimeoutException.

• timeoutDuration — the per-call deadline.
• cancelRunningFuture — interrupt the running task on timeout to free its thread.

@TimeLimiter requires the method to return a CompletableFuture. Without an async return type the aspect silently does nothing. Combine it with a CircuitBreaker so repeated timeouts eventually open the breaker and stop wasting effort.

Note the fallback also returns a CompletableFuture — its signature must match the protected method's return type:

When you stack all three, the aspect order determines behavior. Resilience4j's documented default decoration order, from outer to inner, is:

Retry( CircuitBreaker( RateLimiter( TimeLimiter( Bulkhead( call ) ) ) ) )

• Retry outermost so a retry re-runs the whole protected chain, re-checking the circuit breaker and re-acquiring a rate-limit permit each attempt.
• TimeLimiter inner so each individual attempt has its own deadline — a retry of a timed-out call gets a fresh clock.
• Putting Retry inside the RateLimiter would let one logical call consume several permits per attempt — usually wrong, and it can starve other callers.

With annotations you don't manually order them; Resilience4j enforces this order via aspect precedence.

You cannot tune what you cannot see. With Actuator on the classpath, every instance publishes Micrometer metrics and health indicators. Expose them and watch the key signals:

• resilience4j_ratelimiter_available_permissions — if this sits at zero, you are throttling real traffic; raise the limit or scale out.
• resilience4j_retry_calls tagged kind=successful_with_retry vs failed_with_retry — high failed-with-retry means retries aren't helping; the fault isn't transient.
• resilience4j_timelimiter_calls tagged kind=timeout — rising timeouts signal a degrading dependency before the breaker even opens.

A downstream pricing API occasionally hangs for 30+ seconds instead of returning an error, and these hangs are exhausting your service's request threads. Which Resilience4j primitive most directly addresses this specific failure mode?

You combined three complementary primitives to shape load and contain cascading failures:

• RateLimiter caps calls per window, rejecting excess with RequestNotPermitted so you never overload yourself or a downstream.
• Retry rides out transient faults on idempotent calls, using exponential backoff plus jitter to avoid retry storms.
• TimeLimiter bounds tail latency on async (CompletableFuture) calls, turning hangs into fast timeouts that free threads.

Stack them via annotations; Resilience4j enforces the order Retry → CircuitBreaker → RateLimiter → TimeLimiter → Bulkhead so a retry re-runs the whole protected chain while each attempt keeps its own deadline. Always wire fallbacks for graceful degradation and watch Actuator/Micrometer metrics to tune the limits against real traffic.