Resilience

This content was generated with the assistance of AI and should be verified against the official documentation before being relied on in production.

The reference material consulted while preparing these pages is listed in the section bibliography.

This Backend Development section is a practical guide, focused on Spring Boot services, to making a service tolerate the failures of the services it calls (it complements the SpringBoot Reference). It documents Resilience4j 2.4.0 (released 2026-03-14, Java 17 or later) on Spring Boot 4.1.x and Spring Framework 7.0.x with Java 21, together with the pieces of the Spring ecosystem that sit around it: Spring Cloud CircuitBreaker, the Spring Cloud Gateway and OpenFeign integrations, and the native @Retryable and @ConcurrencyLimit of Spring Framework 7. Where the Spring Boot 3.5 starter differs, the pages show a short "Spring Boot 3" delta. The versions were verified on 4 October 2026.

Next to Resilience4j, the section documents Bucket4j 8.21.0 (released 2026-10-02, Java 17 or later), the token-bucket library for what an in-process limiter cannot do: per-client API quotas, limits shared by every replica through Redis, a JDBC database or a data grid, and one quota of a third-party API shared across instances. Its pages cover the library itself, its Spring Boot integration by hand, through the community bucket4j-spring-boot-starter and in Spring Cloud Gateway, and how it combines with Resilience4j; the Bucket4j pages were verified on 5 October 2026. Start with Resilience4j versus Bucket4j to see which library answers which need.

What resilience means for a Spring Boot service

A service that calls other services inherits their failures. A dependency that answers slowly holds your threads and connections; one that fails intermittently turns every request into a coin toss; one that is down makes every caller wait for a timeout; and a caller that retries aggressively can keep a struggling dependency from ever recovering. Resilience is the set of techniques that keep one failing dependency from becoming your failure:

timeouts so that no call waits forever (TimeLimiter, plus the HTTP client’s own timeouts)
retries with exponential backoff and jitter for transient errors, on idempotent operations only (Retry)
circuit breakers that stop calling a dependency that is clearly failing, and probe it again later (CircuitBreaker)
bulkheads that cap how much of your capacity one dependency can consume (Bulkhead, ThreadPoolBulkhead)
rate limiters that keep you under a dependency’s quota, or keep clients under yours (RateLimiter)
fallbacks that degrade gracefully instead of failing: a cached value, a default, an empty list

Resilience4j is the lightweight, functional fault-tolerance library that Netflix recommends in place of Hystrix, which has been in maintenance mode since 2018. Each pattern is a small module with no dependencies beyond its own modules, composed by decorating a function; the Spring Boot starter adds registries bound to application.yml, annotations, Actuator endpoints, health indicators and Micrometer metrics.

This section is for developers who:

build or maintain Spring Boot services that call other HTTP, gRPC or database-backed services, and want to know which pattern answers which failure
are on Spring Boot 4 (or still on 3.5) and need the starter, the AspectJ dependency and the configuration that actually work, because the official Resilience4j documentation does not cover Spring Boot 4
come from Hystrix, Spring Retry or Spring Cloud Netflix, and need the migration path
want to test the failure paths, observe them in production, and tune the numbers from real traffic

The version baseline

Table 1. Versions the pages were written and run against
Component	Version
Resilience4j	2.4.0 (2026-03-14), group `io.github.resilience4j`; no 3.x has been released
`resilience4j-spring-boot4` / `resilience4j-spring-boot3`	2.4.0, both needing `spring-boot-starter-actuator`; Boot 4 needs `spring-boot-starter-aspectj`, Boot 3 needs `spring-boot-starter-aop`
Spring Boot	4.1.1 (baseline); 3.5.16 for the deltas
Spring Framework	7.0.9 (6.2.19 on Boot 3.5, which has no native resilience API)
Spring Cloud / Spring Cloud CircuitBreaker	2025.1.3 "Oakwood" / 5.0.3 (which still pins Resilience4j 2.3.0 and the Boot 3 starter)
Java	21 (Resilience4j 2.4.0 itself needs 17)
Bucket4j	8.21.0 (2026-10-02), group `com.bucket4j`, artifacts `bucket4j_jdk17-*` imported through `bucket4j_jdk17-bom`; no 9.x has been released
`bucket4j-spring-boot-starter` (community project)	0.20.0-RC1 for Spring Boot 4.1 (pre-release; no GA yet), 0.14.0 for Spring Boot 4.0, 0.13.0 for Spring Boot 3.5
Spring Cloud Gateway (Bucket4j filters)	5.0.3, Web MVC and WebFlux; Bucket4j is an optional dependency the application declares itself

The Resilience4j BOM does not manage resilience4j-spring-boot4, and Spring Boot does not manage Resilience4j at all, so the Maven snippets import the BOM and pin the starter explicitly. The Getting Started page has the details, and Migration & What’s Changed collects every place where the official readme.io documentation is stale. Spring Boot does not manage Bucket4j either, so the Bucket4j pages import bucket4j_jdk17-bom; Bucket4j: Overview and Getting Started has the module table, and Bucket4j: Migration & What’s Changed collects the places where the Bucket4j reference is stale.

The Bookshelf scenario

Every example builds on Bookshelf, the book-catalogue domain already used by the Python FastAPI, NestJS, Django, Next.js and Kubernetes sections, so that the stacks can be compared page by page. Here it is a Spring Boot 4.1 bookshelf-service (Java 21, virtual threads enabled) that calls four downstream dependencies. Each dependency motivates one set of patterns:

Dependency Behaviour Patterns

Dependency	Behaviour	Patterns
`pricing-service`	Slow and flaky.	CircuitBreaker, TimeLimiter and a short Retry, with a fallback to the last known price.
A third-party ISBN-metadata API	Has a request quota and answers 429 or 503.	A client-side RateLimiter, a Bulkhead, and Retry with exponential backoff and jitter that honours `Retry-After`.
`recommendations-service`	Expensive and optional.	A ThreadPoolBulkhead with a CircuitBreaker and a TimeLimiter, degrading to an empty list.
`reviews-service`	Called reactively through `WebClient`.	The Reactor operators of `resilience4j-reactor`.

pricing-service

Slow and flaky.

CircuitBreaker, TimeLimiter and a short Retry, with a fallback to the last known price.

A third-party ISBN-metadata API

Has a request quota and answers 429 or 503.

A client-side RateLimiter, a Bulkhead, and Retry with exponential backoff and jitter that honours Retry-After.

recommendations-service

Expensive and optional.

A ThreadPoolBulkhead with a CircuitBreaker and a TimeLimiter, degrading to an empty list.

reviews-service

Called reactively through WebClient.

The Reactor operators of resilience4j-reactor.

Spring Cloud Gateway sits in front of bookshelf-service with a CircuitBreaker filter, the service’s own search endpoint is protected by a RateLimiter that answers 429 with Retry-After, and the tests inject faults with WireMock and Toxiproxy (through Testcontainers).

Figure 1. The Bookshelf dependency map, annotated with the pattern that guards each call

Rate limits and quotas with Bucket4j

The Bucket4j pages extend the same service with the limits an in-process limiter cannot enforce:

Need Behaviour Bucket4j answer

Need	Behaviour	Bucket4j answer
A public REST API with per-API-key plans	Most pages use a free plan of 20 requests per minute, pro 200 and partner 2 000; the comparison page uses 100 per hour plus 10 per second for free. The quota must hold across every replica.	One bucket per API key, its configuration chosen by plan, stored in Redis through Lettuce; rejections answer 429 with `Retry-After`, `X-Rate-Limit-Remaining` and an RFC 9457 ProblemDetail.
The third-party ISBN-metadata API	Its daily quota (1 000 calls) applies to the whole service, not to each replica.	One distributed bucket shared by every replica, where the Resilience4j RateLimiter above admits the limit once per replica.
The `search` endpoint	Expensive.	Weighted consumption: each call costs 5 tokens.
Teams without Redis	Need the same limits.	A PostgreSQL (JDBC) variant of the bucket store, with its table created by Flyway.
Spring Cloud Gateway	Sits in front of every replica.	A coarse per-client limit at the edge with the Web MVC Bucket4j filter.

A public REST API with per-API-key plans

Most pages use a free plan of 20 requests per minute, pro 200 and partner 2 000; the comparison page uses 100 per hour plus 10 per second for free. The quota must hold across every replica.

One bucket per API key, its configuration chosen by plan, stored in Redis through Lettuce; rejections answer 429 with Retry-After, X-Rate-Limit-Remaining and an RFC 9457 ProblemDetail.

The third-party ISBN-metadata API

Its daily quota (1 000 calls) applies to the whole service, not to each replica.

One distributed bucket shared by every replica, where the Resilience4j RateLimiter above admits the limit once per replica.

The search endpoint

Expensive.

Weighted consumption: each call costs 5 tokens.

Teams without Redis

Need the same limits.

A PostgreSQL (JDBC) variant of the bucket store, with its table created by Flyway.

Spring Cloud Gateway

Sits in front of every replica.

A coarse per-client limit at the edge with the Web MVC Bucket4j filter.

Resilience4j keeps guarding the outbound calls, including the calls to the bucket store itself, so a Redis outage fails open or closed deliberately. The Bookshelf with both libraries puts the two together.

The final layout

The layout below is where the pages end up. Individual examples sit in whichever package keeps them short (most in the base package com.example.bookshelf), so treat the sub-packages as the tidy version of the same classes.

bookshelf-service/
├── pom.xml                                   # resilience4j-bom + resilience4j-spring-boot4 pinned,
│                                             # spring-boot-starter-aspectj, -actuator, -web, -webflux
└── src/
    ├── main/
    │   ├── java/com/example/bookshelf/
    │   │   ├── BookshelfApplication.java
    │   │   ├── pricing/                      # PricingClient (@CircuitBreaker, @TimeLimiter, fallback)
    │   │   ├── isbn/                         # IsbnMetadataClient (@RateLimiter, @Retry, @Bulkhead)
    │   │   ├── recommendations/              # RecommendationsClient (@Bulkhead(type = THREADPOOL))
    │   │   ├── reviews/                      # ReviewsClient (WebClient + Reactor operators)
    │   │   ├── search/                       # SearchController (@RateLimiter, 429 + Retry-After)
    │   │   ├── config/                       # BookshelfResilienceConfig (customizers, Clock)
    │   │   ├── MdcContextPropagator.java     # named in application.yml
    │   │   └── TransientHttpFailure.java     # named in application.yml
    │   └── resources/
    │       ├── application.yml               # shown below
    │       ├── application-test.yml          # tiny windows and waits
    │       └── application-local.yml         # breakers that stay closed while debugging
    └── test/java/com/example/bookshelf/      # registry unit tests, @SpringBootTest aspect checks,
                                              # WireMock faults, Toxiproxy (Testcontainers)

The configuration file is the complete resilience configuration of the service. It is the one explained, key by key, on Spring Boot Configuration, where its effective values were read back from the registries on Spring Boot 4.1.1 and 3.5.16.

application.yml of bookshelf-service

spring:
  application:
    name: bookshelf-service

resilience4j:
  circuitbreaker:
    tags:
      application: ${spring.application.name}
    configs:
      default:                                  # what an unlisted breaker gets
        slidingWindowType: COUNT_BASED
        slidingWindowSize: 20
        minimumNumberOfCalls: 10
        failureRateThreshold: 50
        waitDurationInOpenState: 30s
        permittedNumberOfCallsInHalfOpenState: 3
        automaticTransitionFromOpenToHalfOpenEnabled: true
        registerHealthIndicator: true
        eventConsumerBufferSize: 50
        recordExceptions:
          - org.springframework.web.client.ResourceAccessException
          - org.springframework.web.client.HttpServerErrorException
          - java.util.concurrent.TimeoutException
        ignoreExceptions:
          - org.springframework.web.client.HttpClientErrorException
    instances:
      pricing:                                  # critical, high traffic: time-based window
        baseConfig: default
        slidingWindowType: TIME_BASED
        slidingWindowSize: 10
        minimumNumberOfCalls: 20
        slowCallDurationThreshold: 800ms
        slowCallRateThreshold: 70
        waitDurationInOpenState: 20s
        enableExponentialBackoff: true
        exponentialBackoffMultiplier: 2
        exponentialMaxWaitDurationInOpenState: 2m
        permittedNumberOfCallsInHalfOpenState: 5
        maxWaitDurationInHalfOpenState: 10s
        allowHealthIndicatorToFail: false
      isbn:                                     # third-party API: jitter the probes
        baseConfig: default
        waitDurationInOpenState: 10s
        enableRandomizedWait: true
        randomizedWaitFactor: 0.25
        registerHealthIndicator: false
      recommendations:                          # optional feature: open early, tolerate slowness
        baseConfig: default
        failureRateThreshold: 30
        slowCallDurationThreshold: 1s
      reviews:
        baseConfig: default

  retry:
    configs:
      default:
        maxAttempts: 3
        waitDuration: 200ms
        enableExponentialBackoff: true
        exponentialBackoffMultiplier: 2
        enableRandomizedWait: true
        randomizedWaitFactor: 0.5
        ignoreExceptions:
          - io.github.resilience4j.circuitbreaker.CallNotPermittedException
    instances:
      pricing:
        baseConfig: default
        maxAttempts: 2
        retryExceptions:
          - org.springframework.web.client.ResourceAccessException
      isbn:
        baseConfig: default
        maxAttempts: 4
        exponentialMaxWaitDuration: 5s
        retryExceptionPredicate: com.example.bookshelf.TransientHttpFailure
        eventConsumerBufferSize: 200

  ratelimiter:
    configs:
      default:
        limitForPeriod: 10
        limitRefreshPeriod: 1s
        timeoutDuration: 0
    instances:
      isbn:                                     # client side: stay under the third-party quota
        baseConfig: default
        limitForPeriod: 5
        timeoutDuration: 500ms
        subscribeForEvents: true
        registerHealthIndicator: true
      search:                                   # server side: protect our own endpoint
        baseConfig: default
        limitForPeriod: 3
        limitRefreshPeriod: 2s
        subscribeForEvents: true

  bulkhead:
    configs:
      default:
        maxConcurrentCalls: 10
        maxWaitDuration: 0
    instances:
      isbn:
        baseConfig: default
        maxConcurrentCalls: 2
        maxWaitDuration: 100ms
        writableStackTraceEnabled: false

  thread-pool-bulkhead:
    configs:
      default:
        coreThreadPoolSize: 2
        maxThreadPoolSize: 4
        queueCapacity: 2
        keepAliveDuration: 20ms
        contextPropagators:
          - com.example.bookshelf.MdcContextPropagator
    instances:
      recommendations:
        baseConfig: default

  timelimiter:
    configs:
      default:
        timeoutDuration: 2s
        cancelRunningFuture: true
    instances:
      pricing:
        baseConfig: default
        timeoutDuration: 800ms
      recommendations:
        baseConfig: default
        timeoutDuration: 1s
      reviews:
        baseConfig: default
        timeoutDuration: 300ms
        cancelRunningFuture: false

management:
  endpoints:
    web:
      exposure:
        include: health,circuitbreakers,circuitbreakerevents,retries,ratelimiters,bulkheads,timelimiters,metrics,prometheus
  endpoint:
    circuitbreakers:
      access: read-only                         # no CLOSE / FORCE_OPEN / DISABLE over HTTP
    health:
      show-details: when-authorized
  health:
    circuitbreakers:
      enabled: true
    ratelimiters:
      enabled: true

Source: Resilience4j: Spring Boot 2 & 3 and the property classes at the v2.4.0 tag; the same file, bound and run, is on Spring Boot Configuration.

The Grafana dashboard

Resilience4j ships a dashboard in its repository (grafana_dashboard.json). It reads the resilience4j.* meters that Micrometer exports to Prometheus and shows circuit-breaker states, failure rate, call rate and call duration, retry calls and the semaphore bulkhead. The observability page imports it for Bookshelf, explains the application tag it filters on and the panel that queries a meter 2.4.0 no longer publishes, and lists the panels to add for rate limiters, time limiters and thread-pool bulkheads. See Observability.

Reading path

The pages are ordered so that each one builds on the previous ones. Read them in this order the first time, then use them as a reference:

Foundations: why remote calls fail and which pattern answers which failure, then the dependencies and a first @CircuitBreaker, then the registry, configuration and decorator model that every module shares.
Core modules: CircuitBreaker first (the deepest page), then Retry, RateLimiter, Bulkhead and TimeLimiter, then fallbacks and how the patterns compose, then Cache and Hedge.
Spring Boot integration: the complete application.yml, the annotations and their aspect order, programmatic use without annotations, reactive code, observability, Spring Cloud CircuitBreaker, the Gateway and OpenFeign, and the native resilience of Spring Framework 7.
Quality and operations: testing the failure paths, production tuning and anti-patterns, and migration.
Bucket4j: first Resilience4j versus Bucket4j (which library answers which need), then the Bucket4j core (overview, token bucket and bandwidths, the Bucket API), distributed rate limiting and its backends, the Spring Boot integration (by hand, with the community starter, in Spring Cloud Gateway), and observability, testing, the production checklist and migration.
The cheat sheets: the Resilience4j pages and the Bucket4j pages, each condensed onto one printable page.

Readers who already run Resilience4j can start with Migration & What’s Changed, then Annotations & Aspect Order and Production Tuning & Anti-patterns. Readers who only need rate limits or API quotas can read RateLimiter and Resilience4j versus Bucket4j, then Bucket4j: Overview and Getting Started. The Cheat Sheets (PDF) condense the section for quick lookup.

mindmap root((Resilience)) Foundations Resilience fundamentals Getting started Registries and decorators Core modules CircuitBreaker Retry RateLimiter Bulkhead TimeLimiter Fallbacks and composition Cache and Hedge Spring Boot integration Configuration Annotations and aspect order Programmatic usage Reactive Kotlin RxJava Observability Spring Cloud CircuitBreaker Gateway and OpenFeign Spring Framework native Quality and operations Testing Production tuning Migration Bucket4j Resilience4j versus Bucket4j Token bucket and Bucket API Distributed and backends Manual starter and Gateway Observability testing checklist Cheat sheets Two A4 pages

Figure 2. The section at a glance

What’s covered

Each page builds on the Bookshelf scenario, lists every configuration property with its default where it has any, and ends with the official sources it derives from.

Foundations

Resilience Fundamentals — failure modes (latency, partial and cascading failure, retry storms, thundering herds, resource exhaustion), the pattern catalogue, idempotency as the precondition for retries, fail fast versus degrade gracefully, where resilience belongs (client library, gateway, service mesh), the history from Hystrix to Resilience4j, and the same patterns in Quarkus, NestJS and .NET.
Getting Started — the module map, Maven and Gradle (Kotlin DSL) dependencies for Boot 4 and Boot 3, why AspectJ is optional but annotations need it, a first @CircuitBreaker with a fallback on the pricing call, and the /actuator/circuitbreakers endpoint.
Registries, Configuration & Decorators — the programming model shared by every module: registries, shared configurations, tags, a custom RegistryStore, registry events, decorating functions, the Decorators builder, per-instance events, the instance-management best practices, and resilience4j-commons-configuration.

Core modules

CircuitBreaker — the CLOSED, OPEN and HALF_OPEN state machine and the special states, manual transitions, count-based and time-based sliding windows, failure rate versus slow-call rate, every property with its default, what counts as a failure, CallNotPermittedException, events and metrics, and a worked tuning example.
Retry — how maxAttempts counts the first call, every property, the interval functions (fixed, exponential, randomized), the Boot backoff keys and their traps, jitter, retry storms and budgets, honouring Retry-After, idempotency, and a comparison with Spring Framework 7 @Retryable.
RateLimiter — the cycle model, AtomicRateLimiter versus SemaphoreBasedRateLimiter, drainPermissionsOnResult, changing limits at runtime, RequestNotPermitted and HTTP 429, client-side throttling of the ISBN API, and what an in-process limiter does not do.
Bulkhead — SemaphoreBulkhead versus FixedThreadPoolBulkhead, every property, choosing between them, virtual threads and @ConcurrencyLimit, context propagation (MDC, security context, tracing), and BulkheadFullException.
TimeLimiter — timeoutDuration and cancelRunningFuture, the blocking Future and non-blocking CompletionStage forms, why @TimeLimiter needs an asynchronous return type, and timeout layering across the HTTP client, the TimeLimiter and the gateway.
Fallbacks & Composition — fallback semantics, the method-resolution rules, fallbacks for reactive and asynchronous types, composing patterns with Decorators or annotations, the recommended order and why, and the *AspectOrder properties.
Cache & Hedge — the JCache (JSR-107) Cache decorator, its relation to Spring’s @Cacheable, and the resilience4j-hedge module for tail latency.

Spring Boot integration

Spring Boot Configuration — the complete YAML structure for every resilience4j.* prefix, configs, instances and baseConfig, durations and class names, Boot-only properties, customizers, precedence, profiles, SpEL instance names, @RefreshScope registries, a property reference for every module, and the complete Bookshelf configuration.
Annotations & Aspect Order — the six annotations and their attributes, supported return types, Spring AOP proxy pitfalls (self-invocation, final and private methods, @Transactional ordering), stacking, the effective default order, and changing it.
Programmatic Usage — injecting the auto-configured registries, decorating RestClient, WebClient, the JDK HttpClient and @HttpExchange clients without annotations, and mapping 5xx and 429 responses to recorded failures.
Reactive, Kotlin & RxJava — the resilience4j-reactor operators with transformDeferred, annotations on Mono and Flux, RxJava 2 and 3, Kotlin suspend functions and Flow, and virtual threads as the blocking alternative.
Observability — every Actuator endpoint, the circuitbreakers write operation and how to secure it, health indicators and keeping them out of the liveness probe, every Micrometer meter, Grafana, logging the event streams, alerting rules, and tracing through bulkhead threads.
Spring Cloud CircuitBreaker — the vendor-neutral CircuitBreakerFactory, the Resilience4j starters and customizers, the TimeLimiter that is on by default, bulkhead wrapping, precedence, the Framework Retry implementation, and Resilience4j version alignment.
Gateway & OpenFeign — the Spring Cloud Gateway CircuitBreaker filter for WebFlux and Web MVC, 503 and 504 semantics, the Redis RequestRateLimiter, OpenFeign circuit-breaker support, and plain Resilience4jFeign.
Spring Framework Native Resilience — @Retryable, @ConcurrencyLimit and @EnableResilientMethods, the programmatic RetryTemplate, the migration from the archived Spring Retry, a feature comparison with Resilience4j and Spring Cloud CircuitBreaker, and a decision guide.

Quality and operations

Testing Resilience — unit tests that drive breakers through the registry, deterministic time with a custom Clock, @SpringBootTest checks that the aspects apply, fault injection with WireMock and Toxiproxy, asserting on Actuator and meters, StepVerifier, and chaos testing.
Production Tuning & Anti-patterns — choosing thresholds from real traffic, one instance per backend, retry amplification, timeout ordering, load shedding, runbooks such as forcing a breaker open, and the anti-patterns table.
Migration & What’s Changed — Hystrix to Resilience4j, 1.x to 2.x, Boot 2 to 3 to 4, Spring Retry to Spring Framework 7, the 2.3.0 and 2.4.0 changes, and the full list of places where the readme.io documentation is stale.

Cheat sheet

Cheat Sheets (PDF) — two printable A4 pages: the Resilience4j pages on one, the Bucket4j pages on the other.

Alternatives and complementary libraries

Bucket4j is the token-bucket rate-limiting library that complements Resilience4j: per-client quotas, limits shared by every replica, and quotas of third-party APIs. Gateway-level quotas, plans and API managers are the subject of a separate follow-up issue (#184).

Positioning

Resilience4j versus Bucket4j — an outbound fault-tolerance toolkit versus a rate-limiting and quota library, the cycle model and the token bucket side by side with the burst at a cycle boundary, the feature comparison, a decision guide, using both together (fail open or fail closed when the bucket store is down, Retry honouring Retry-After), and the same idea in other stacks.

Bucket4j core

Bucket4j: Overview and Getting Started — what Bucket4j is and when to use it, the 8.21.0 module table and artifact history, Maven and Gradle setup with bucket4j_jdk17-bom, a first local bucket, and the ecosystem.
Bucket4j: Token Bucket and Bandwidths — the algorithm and its formula, other limiter shapes, the Bandwidth.builder() stages and refill styles, initial tokens and ids, several bandwidths per bucket, long periods and short bursts, technical limitations, and the deprecated API.
Bucket4j: The Bucket API — tryConsume, ConsumptionProbe, weighted consumption, returning tokens, the verbose, blocking and scheduling APIs, replaceConfiguration with every TokensInheritanceStrategy, listeners, TimeMeter, synchronization strategies, and the path to HTTP 429.

Bucket4j distributed

Bucket4j: Distributed Rate Limiting — why local limits multiply with replicas, ProxyManager and AsyncProxyManager, RemoteBucketBuilder, the atomicity models, every client-side setting, key design, implicit configuration replacement, optimizations, clock skew, and the distributed checklist.
Bucket4j: Backends — every 8.21.0 backend module with its builder and atomicity model, Redis and JDBC in depth, the data grids, MongoDB, Couchbase, Memcached, Cassandra, Caffeine, and choosing a backend.

Bucket4j and Spring Boot

Bucket4j: Spring Boot Manual Integration — plans as @ConfigurationProperties, a ProxyManager bean over Redis or PostgreSQL, a servlet filter or interceptor and its order relative to Spring Security, key resolution, 429 with Retry-After and a ProblemDetail, a WebFlux WebFilter, a method-level limiter, the shared outbound quota, and what to do when the store is down.
Bucket4j: The Spring Boot Starter — the community bucket4j-spring-boot-starter, its versions and modules, every property with its default, SpEL cache keys, the filter order and Spring Security, headers, @RateLimiting, the Lettuce RedisClient bean, metrics, and starter versus manual integration.
Bucket4j: Spring Cloud Gateway — the Web MVC Bucket4jFilterFunctions.rateLimit filter, the WebFlux Bucket4j limiter of RequestRateLimiter, the Redis limiter for contrast, version alignment, and edge versus in-service limits.

Bucket4j quality and operations

Bucket4j: Observability — Micrometer through BucketListener, request-level meters, the starter’s meters and endpoint, Prometheus, Grafana, alerting, logging and tracing 429 responses, and a HealthIndicator for the bucket store.
Bucket4j: Testing Rate Limits — deterministic time with a custom TimeMeter, concurrency tests, MockMvc and WebTestClient assertions, a tiny-bandwidth test profile, Testcontainers with Redis and PostgreSQL, a Redis outage with Toxiproxy, and testing the starter’s YAML.
Bucket4j: Production Checklist — the official generic and distributed checklists, eight anti-patterns, capacity planning, cleaning up expired JDBC rows, and login limits and API keys.
Bucket4j: Migration & What’s Changed — 7.x to 8.x, the 8.5.0 bandwidth builder, the 8.11.1 artifact rename, the 8.16 to 8.21 entry points and modules, the starter from 0.12 to 0.20, and the full table of places where the official documentation is stale.

Where related material lives elsewhere on this site

The section links to existing pages instead of repeating them.

Topic Where

Topic	Where
Base Actuator, Micrometer and Prometheus setup	Metrics & Observability
`RestClient`, `WebClient` and gRPC clients that get decorated	REST APIs and gRPC APIs
Reactor basics, virtual threads and coroutines	Reactive Programming and Concurrency Alternatives
Configuration, profiles and `@RefreshScope`	Configuration & Profiles
Caching with Spring’s `@Cacheable`, and a breaker around a shared cache	Caching and Near-Far Caches
JUnit, Mockito and Testcontainers	Unit & Integration Testing and Spring Boot Integration Tests with Testcontainers
Messaging retries are Kafka-native, not Resilience4j	Messaging with Kafka and Spring Boot: Apache Kafka
Retry and skip in batch jobs; guarding remote calls from a batch job	Fault tolerance: skip & retry and Cloud-native batch
The API gateway pattern and the cost of many network hops	API Gateway and Backends for Frontends and Benefits and Drawbacks of Microservices
Rate limiting and concurrency for LLM calls	Spring AI: Production & Deployment
The same patterns in other stacks	Quarkus Fault Tolerance and Resilience, Quarkus vs. Spring Boot, NestJS Resilience, Idempotency & Locks and ASP.NET Core HTTP Client and Resilience
Liveness and readiness probes (never wire breaker health into liveness)	Health Probes and Container Lifecycle

Base Actuator, Micrometer and Prometheus setup

Metrics & Observability

RestClient, WebClient and gRPC clients that get decorated

REST APIs and gRPC APIs

Reactor basics, virtual threads and coroutines

Reactive Programming and Concurrency Alternatives

Configuration, profiles and @RefreshScope

Configuration & Profiles

Caching with Spring’s @Cacheable, and a breaker around a shared cache

Caching and Near-Far Caches

JUnit, Mockito and Testcontainers

Unit & Integration Testing and Spring Boot Integration Tests with Testcontainers

Messaging retries are Kafka-native, not Resilience4j

Messaging with Kafka and Spring Boot: Apache Kafka

Retry and skip in batch jobs; guarding remote calls from a batch job

Fault tolerance: skip & retry and Cloud-native batch

The API gateway pattern and the cost of many network hops

API Gateway and Backends for Frontends and Benefits and Drawbacks of Microservices

Rate limiting and concurrency for LLM calls

Spring AI: Production & Deployment

The same patterns in other stacks

Quarkus Fault Tolerance and Resilience, Quarkus vs. Spring Boot, NestJS Resilience, Idempotency & Locks and ASP.NET Core HTTP Client and Resilience

Liveness and readiness probes (never wire breaker health into liveness)

Health Probes and Container Lifecycle

Bibliography

Every source used to write this section, each linked to its official documentation. Individual pages list the subset they derive from under their own == References heading. Where the official Resilience4j documentation is stale, the pages follow the v2.4.0 source and link both.