Fault Tolerance and Resilience

delay/jitter together produce a randomised back-off in [delay - jitter, delay + jitter] for each attempt — jitter exists specifically to stop many callers retrying a recovering downstream service in lockstep and re-overwhelming it the instant it comes back. maxDuration bounds total time spent retrying regardless of maxRetries, so a slow failure mode cannot keep retrying far longer than the caller can tolerate. retryOn narrows retries to specific exception types (anything else propagates immediately); abortOn is the inverse — exceptions that should never be retried even if they match `retryOn’s type hierarchy, typically because they indicate the request itself was wrong rather than that the call failed transiently.

A method that has not returned within the given duration is interrupted and a org.eclipse.microprofile.faulttolerance.exceptions.TimeoutException is raised in its place — this composes with @Retry (a timeout counts as a retryable failure by default) and is usually the annotation that actually bounds an otherwise-unbounded blocking call, since neither @Retry nor @CircuitBreaker alone limits how long a single attempt may run.

The semaphore form (the default, for a plain synchronous method) limits how many callers may be executing the method at once — the (6+)`th concurrent caller is rejected immediately with a `BulkheadException rather than queued. The thread-pool form applies only to @Asynchronous methods: it runs on a dedicated bounded thread pool with its own bounded waitingTaskQueue, so excess work queues briefly instead of being rejected outright, at the cost of an extra thread-pool hand-off. Either way, a bulkhead’s purpose is to stop one overloaded or misbehaving downstream dependency from consuming every thread/permit in the caller and starving unrelated calls that share the same process.

requestVolumeThreshold is the minimum number of calls, within a rolling window of that same size, before the circuit can trip at all — it exists so that a handful of early failures right after startup cannot open the circuit on statistically meaningless data. Once at least that many calls have been made, failureRatio is compared against the fraction of them that failed; crossing it opens the circuit. delay is how long the circuit stays open before allowing a single probe call through (transitioning to half-open); successThreshold is how many consecutive successful probe calls are needed, while half-open, before the circuit closes again — a single failed probe reopens it immediately.

fallbackMethod must match the original method’s signature exactly (same parameter types, same or a covariant return type) and runs once every other configured strategy (retries exhausted, circuit open, timeout) has given up — @Fallback is deliberately the outermost annotation in the execution order (see Composing several strategies on one call), since a fallback should only ever run after every recovery attempt has already failed.

io.smallrye.faulttolerance.api.RateLimit is a SmallRye extension beyond the MicroProfile Fault Tolerance specification: it caps a method to at most value invocations per window, rejecting any call beyond that with a RateLimitException, and minSpacing additionally enforces a minimum gap between any two consecutive calls regardless of the window count. Unlike @Bulkhead (which limits concurrent callers), @RateLimit limits throughput over time — the two compose naturally when a downstream dependency has both a concurrency limit and a calls-per-second quota.

io.smallrye.faulttolerance.api.Guard/FaultTolerance builds the same strategies programmatically instead of through annotations — useful when the configuration itself needs to be computed or shared identically across several methods without repeating annotation attributes on each one. @ApplyGuard("inventoryGuard") attaches a named, CDI-produced Guard bean to a method, combining the ergonomics of the annotation-based interceptor with programmatic construction.

Every annotation on this page applies to a method returning java.util.concurrent.CompletionStage/Future (marked @Asynchronous) exactly as it does to a synchronous one, and quarkus-smallrye-fault-tolerance extends this natively to Mutiny’s reactive types:

A method returning Uni<T> needs no @Asynchronous annotation and no adapter — SmallRye Fault Tolerance recognises the reactive return type and applies retry/timeout/circuit-breaker/bulkhead semantics to the subscription rather than to a blocking call, which is what makes it safe to stack directly on reactive data access (see Reactive Data Access) and reactive REST client calls without introducing blocking behaviour.

With quarkus-micrometer (or the OpenTelemetry bridge, see Observability) also present, every fault-tolerance strategy emits its own meters without extra code — retry attempt counts, circuit-breaker state transitions and time spent in each state, bulkhead rejections, and timeout occurrences, each tagged with the method they apply to. This is what makes it practical to notice, say, a circuit breaker flapping between closed and open in production instead of only inferring it from elevated error rates:

Fault tolerance can be turned off globally, which is occasionally useful for isolating whether an observed failure is caused by application logic or by a fault-tolerance strategy itself:

Per the MicroProfile Fault Tolerance specification, every non-fallback strategy (retry, timeout, bulkhead, circuit breaker) can instead be disabled while keeping fallbacks active, via the standard MP_Fault_Tolerance_NonFallback_Enabled=false configuration property — useful for a test profile that wants a fallback’s behaviour exercised without the delay a real retry/timeout would add. A single annotation on a single method can also be disabled individually using the specification’s <fully-qualified-class-name>/<method-name>/<AnnotationType>/enabled=false configuration key pattern, without touching the annotation itself in code.

Retries, bulkheads, and circuit breakers all protect a caller from a struggling downstream dependency; load shedding protects an application itself from being overwhelmed by more concurrent work than it can process, by proactively rejecting a portion of incoming requests once the system is past a healthy operating point rather than queueing them and letting latency balloon for everyone, including requests that arrive after the overload has already passed. This is a property of the HTTP layer serving inbound requests rather than of any one CDI-intercepted method, and the exact configuration surface is intentionally not duplicated here — see the dedicated load-shedding reference guide linked below for the current configuration keys and the algorithm behind them.

Stork resolves a logical service name to a concrete instance list on the consumer side, so a client never hardcodes a downstream URL — it was already introduced briefly on the REST client page via the stork:// URL scheme; this section covers the mechanism itself.

The MicroProfile Fault Tolerance specification fixes this order deliberately: @Fallback sits outermost so it can catch a failure from any inner strategy, including a circuit that is currently open; @Retry wraps @CircuitBreaker so a retried call can still be short-circuited without re-attempting a downstream call known to be failing; @Timeout wraps @Bulkhead so a call already holding a bulkhead permit can still be aborted for taking too long. A single failed attempt can therefore be, in order: rejected by the bulkhead, timed out, counted toward the circuit breaker’s failure ratio, retried, and finally — only once retries are exhausted or the circuit is open — resolved by the fallback.