Retry

Everything the module does fits in one loop. The decorated function runs; if it throws an exception that is retryable (or returns a result that is, when a result predicate is configured), the Retry computes a wait, sleeps, and runs it again, until the call succeeds or maxAttempts calls have been made.

Five facts follow from the source and are easy to get wrong:

A first retry, without Spring, shows the counting:

Source: Resilience4j: Retry and the RetryImpl source at v2.4.0. Run on Resilience4j 2.4.0: 3 invocations, then the original IllegalStateException.

Retry is the outermost pattern by default in the Spring Boot aspect chain (aspect order -5, ahead of the CircuitBreaker, rate limiter, time limiter and bulkhead), which means every attempt passes through the inner patterns and counts in their metrics. The ordering rules and how to change them are in Annotations & Aspect Order.

RetryConfig has no mandatory setting: RetryConfig.ofDefaults() gives 3 attempts, 500 ms apart, retrying every exception. The table lists every property, its default in 2.4.0 (verified in RetryConfig and CommonRetryConfigurationProperties) and where it can be set. Boot properties live under resilience4j.retry.configs.<name> (shared) and resilience4j.retry.instances.<name>; an instance that sets baseConfig takes that configuration’s keys on top of the ones named default (default is always the root of the chain when it exists), and an instance with no baseConfig starts from default alone.

The aspect order is a separate property of the module, resilience4j.retry.retryAspectOrder (default Ordered.LOWEST_PRECEDENCE - 5). The @Retry annotation carries three attributes: name (a SpEL expression is allowed), configuration (a shared configuration key, useful when the name is computed) and fallbackMethod. The deprecated maxRetryAttempts property was removed in 2.0.0 in favour of maxAttempts, and consumeResultBeforeRetryAttempt exists in the code and in the Boot properties although the readme.io Retry page does not list it.

Source: Resilience4j: Retry, RetryConfig and CommonRetryConfigurationProperties at v2.4.0.

The wait is computed by an IntervalFunction: it receives the attempt number (starting at 1, the number of the attempt that just failed) and returns milliseconds. The factories are static methods of io.github.resilience4j.core.IntervalFunction, and each exists in a long milliseconds and a Duration form. Defaults are an initial interval of 500 ms, a multiplier of 1.5 and a randomization factor of 0.5.

Argument checks are strict: an interval below 1 ms, a randomization factor outside 0 to 1 and an attempt number below 1 all throw IllegalArgumentException.

Source: Resilience4j: Retry (IntervalFunction) and IntervalFunction at v2.4.0. The numbers in the table and in the figure were computed by calling these factories on 2.4.0.

Two properties of the capped, jittered form matter in practice. The cap is applied after the jitter, so the upper end of the range is exactly the cap, and once the exponential value exceeds the cap divided by one minus the factor the jitter disappears entirely: in the example above every wait from the sixth retry on is exactly 8000 ms for every client. Choose a cap well above the point where you expect to give up, or stop retrying before it is reached.

In Spring Boot the interval function cannot be set in YAML (there is no intervalFunction property), so the properties enableExponentialBackoff, enableRandomizedWait and friends choose one of the factories above, always starting from waitDuration:

The combinations map as follows: both flags select ofExponentialRandomBackoff, only enableExponentialBackoff selects ofExponentialBackoff, only enableRandomizedWait selects ofRandomized, and neither keeps the fixed waitDuration.

Source: Resilience4j: Spring Boot 2 & 3 (the properties) and CommonRetryConfigurationProperties at v2.4.0 (configureRetryIntervalFunction). Bound and run on Spring Boot 4.1.1: for attempts 1 to 8 every computed wait stayed inside the range implied by 200 ms, multiplier 2, a 5 s cap and factor 0.5. The class named by retryExceptionPredicate is shown in the idempotency section.

Reading the binder source and running it exposed five traps. None is documented on readme.io:

An instance that is not listed in YAML but is requested by name (for example through @Retry(name = "unknown")) takes the default configuration; verified on Boot 4.1.1.

Source: Resilience4j: Spring Boot 2 & 3. The aspect needs spring-boot-starter-aspectj on Boot 4 (see Getting Started). Verified against a WireMock stub of the ISBN API: answers 503, 502, 200 produced exactly three requests and the title; an always-503 stub produced four requests (maxAttempts: 4) and the original HttpServerErrorException reached the caller.

A retry multiplies load by design. When many clients fail at once because a dependency hiccuped, a fixed-delay retry sends them all back at the same instant, then again, as a synchronised wave: a retry storm that can keep a recovering service down (the thundering herd of Resilience Fundamentals). Two things break it: spreading the retries in time, and limiting how many retries exist at all.

Spread them with exponential backoff and jitter. Backoff reduces the pressure over time; jitter removes the synchronisation. The right-hand panel of the figure is measured, not illustrative: 1000 clients that fail at the same moment and retry with ofExponentialBackoff(500, 2.0, 8000) all land within the same 50 ms bucket (1000 of 1000), while with ofExponentialRandomBackoff(500, 2.0, 0.5, 8000) the busiest 50 ms bucket held 123. Prefer the jittered form for any call to a shared dependency, and remember that the jitter vanishes once the cap is reached (previous section).

Count the layers. Retries nest, and they multiply. If a controller retries 3 times, the service it calls retries 3 times, and that service’s client retries 3 times, one failing leaf call becomes 27. Measured with three nested Retry decorators of maxAttempts(3): the failing bottom call ran 27 times. Retry at one layer, normally the one closest to the caller that can make a decision, and keep the others at 1.

Cap the total with a budget. A retry budget limits retries to a fraction of normal traffic, so that a total outage cannot turn into a multiple of it. Resilience4j has no built-in budget, but retryOnException is a natural hook: it is evaluated on every failure and can consult a shared counter. The class below allows retries up to 10% of requests plus a small floor:

Source: the idea of limiting retries globally is the one behind retry throttling in the gRPC retry guide; this class is an original sketch, not a Resilience4j or Spring feature. Run: 50 requests against a service that always fails produced 57 calls (50 first attempts plus 7 retries) instead of 150. The predicate is also consulted for the final failure of a call, so the budget can be consumed slightly ahead of the actual retries.

Do not retry into an open circuit. With the default aspect order the retry wraps the circuit breaker, so once the breaker opens, each retry attempt is rejected with CallNotPermittedException. That is fast but pointless; exclude it so the call fails at once, and let the fallback handle it:

Source: Resilience4j: Retry and the README at v2.4.0 (Decorators). Run: with the breaker open the body ran 0 times and the retry counted one failed call without retry attempt. The circuit breaker itself is in CircuitBreaker; how the patterns combine is in Fallbacks & Composition.

When a server says how long to wait, believe it. 429 Too Many Requests (RFC 6585) and 503 Service Unavailable may carry a Retry-After header, either a number of seconds or an HTTP date (RFC 9110, section 10.2.3). A backoff computed blindly will often retry too early, burn an attempt and earn another refusal. The IntervalBiFunction receives the outcome of the failed attempt, so it can read the header from the exception and take the larger of the computed backoff and the server’s request, or stop when the server asks for longer than the caller can afford:

Source: the IntervalBiFunction contract in resilience4j-core at v2.4.0; the class itself is an original idiom, verified below.

Wire it in YAML (the class needs the public no-argument constructor it has):

Source: RFC 9110: HTTP Semantics (Retry-After), RFC 6585 (429) and the IntervalBiFunction source at v2.4.0. Run against a WireMock stub of the ISBN API on Spring Boot 4.1.1: a 429 with Retry-After: 1 followed by a 200 made the second request arrive after at least one second (measured about 1.2 s, where the computed backoff alone would be 100 to 300 ms); a 429 with Retry-After: 3600 made exactly one request and the TooManyRequests exception reached the caller. There is no standard, documented hook that reads Retry-After for you; this class is the idiom.

A retry re-executes the call, so the question is what re-execution does. Retry only operations whose repetition has no extra effect, and only failures that are plausibly transient.

The Bookshelf encodes this table as a predicate class that the YAML names with retryExceptionPredicate:

Source: RFC 9110: HTTP Semantics (method semantics) and REST APIs for the RestClient exception types. Run: a 404 produced one request and the HttpClientErrorException.NotFound reached the caller; the transient predicate is the one used by the isbn instance above. Note that ResourceAccessException also covers read timeouts, so use this predicate only for idempotent calls, or split the connect-time failures out.

Retries that belong to the messaging stack are not Resilience4j’s job: a Kafka consumer retries with the listener container’s error handler and retry topics, described in Kafka Messaging and Spring Boot Kafka, and Spring Batch has its own skip-and-retry policy in Fault Tolerance: Skip and Retry.

Each Retry has an EventPublisher with four event types, all subclasses of RetryEvent:

Source: Resilience4j: Retry (consume emitted events) and the event classes at v2.4.0. Run: a call that succeeded on its third attempt produced RETRY (attempt 1), RETRY (attempt 2), SUCCESS (after 2); an ignored exception produced IGNORED_ERROR; a call that exhausted three attempts produced two RETRY events and one ERROR (after 3).

The same instance exposes four counters through retry.getMetrics(): successful calls without a retry, successful calls with a retry, failed calls without a retry (ignored exceptions) and failed calls after retrying. With Micrometer they become resilience4j.retry.calls with the tags name and kind (successful_without_retry, successful_with_retry, failed_without_retry, failed_with_retry). Spring Boot also publishes the retries and retryevents Actuator endpoints (the latter fed by eventConsumerBufferSize). A rising successful_with_retry rate is the early-warning signal; a dashboard and alerting recipe is in Observability and the base Actuator setup in Metrics and Observability.

Resilience4j Retry also works for asynchronous code: executeCompletionStage schedules each retry on a ScheduledExecutorService instead of sleeping a thread, and the Reactor and RxJava operators are covered in Reactive, Kotlin & RxJava.

Source: Resilience4j: Retry. Run: a stage that failed twice and then succeeded completed after exactly three calls.

Spring Framework 7.0 added native resilience annotations, @Retryable and @ConcurrencyLimit, enabled by @EnableResilientMethods in the org.springframework.resilience.annotation package, with the programmatic RetryTemplate and RetryPolicy in org.springframework.core.retry. They replace the archived Spring Retry project. They are a sound choice when all you need is a bounded retry and no extra dependency. They do not provide a circuit breaker, rate limiter, time limiter, metrics endpoint or health indicator, so they stop being enough where those matter. Spring’s own pages are covered in Spring Framework Native Resilience; this section compares only the retry feature.

The attempt-count difference is the one that bites when migrating a number from one to the other: the same figure of 3 means three calls in Resilience4j and four in Spring.

Source: Spring Framework: Resilience features and Core Spring Resilience Features; the attributes and defaults were read from the 7.0.9 sources of org.springframework.resilience.annotation.Retryable. Run on Spring Framework 7.0.9 in a plain annotation-configured context: a method with only delay = 10 set (other attributes at their defaults) was invoked 4 times and rethrew the original IllegalStateException; maxRetries = 2 with includes = IOException.class invoked the method 3 times; an excluded exception was invoked once.

Use the native annotation when the need is a plain bounded retry on a method and you want no extra dependency. Use Resilience4j Retry when you need result-based retry, a delay that depends on the response, retry events and metrics, a per-instance configuration in YAML, or one programming model alongside the circuit breaker, bulkhead and rate limiter. The two can coexist, but then their ordering needs thought: two retry layers multiply, as in the previous section.