How to Add Fault Tolerance With SmallRye in Quarkus
Make Quarkus calls resilient with SmallRye Fault Tolerance: @Timeout, @Retry, @CircuitBreaker, @Fallback and @Bulkhead, with sensible values and their limits.

A call to another service can be slow, fail, or fail intermittently, and a request that depends on it inherits all three. Quarkus implements MicroProfile Fault Tolerance through SmallRye, which turns the standard defences into annotations on CDI bean methods: a timeout, a retry, a circuit breaker, a fallback and a bulkhead. The annotations are quick to add and are easy to use wrongly, because their effect depends on how they combine, on the proxy they rely on and on the idempotency of the call. This post shows each annotation, the order in which they apply, the settings that matter and the checks to run. It uses Quarkus 3 and JDK 25. The general reasoning is in retries, timeouts and bulkheads.
Dependency
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-smallrye-fault-tolerance</artifactId>
</dependency>The extension implements the MicroProfile Fault Tolerance API and adds its own, with extra annotations and programmatic APIs. The annotations apply to methods of CDI beans, such as @ApplicationScoped services, and to REST client interfaces.
The annotations together
@ApplicationScoped
public class PriceService {
@Inject @RestClient PriceApi api;
@Timeout(800)
@Retry(maxRetries = 2, delay = 100, jitter = 50, retryOn = IOException.class)
@CircuitBreaker(requestVolumeThreshold = 10, failureRatio = 0.5, delay = 5000)
@Bulkhead(20)
@Fallback(fallbackMethod = "cachedPrice")
public Price price(String sku) {
return api.price(sku);
}
Price cachedPrice(String sku) {
return cache.lastKnown(sku);
}
}The call has an 800 ms time limit per attempt, up to two retries for I/O failures with a short randomised delay, a circuit breaker that opens when half of the last ten calls failed, at most twenty concurrent calls and a fallback to cached data when everything else gives up. Each is optional. The fallback method must have the same parameters and return type.
What each one does
@Timeout bounds the call: after the given milliseconds the caller receives a TimeoutException, even though the underlying work may still be running. It interrupts the thread where it can, which a blocking socket read does not always honour, so combine it with the client's own timeouts.
@Retry repeats a failed invocation. maxRetries, delay, jitter and maxDuration control the schedule, and retryOn and abortOn restrict the exceptions. The SmallRye extension adds exponential backoff through @ExponentialBackoff.
@CircuitBreaker tracks recent outcomes in a rolling window. When the failure ratio over requestVolumeThreshold calls reaches failureRatio, it opens, and calls fail immediately with CircuitBreakerOpenException for delay milliseconds without touching the dependency. Then it half-opens, lets some trial calls through, and closes again after successThreshold successes. It protects a struggling dependency from being hammered and your threads from waiting on it.
@Bulkhead limits concurrent invocations. In its semaphore form, the default for synchronous methods, excess calls fail at once with BulkheadException. In the thread-pool form for asynchronous methods, there is a queue (waitingTaskQueue) first.
@Fallback supplies an alternative result when the call fails for any reason, including the other annotations' exceptions. A fallbackMethod is the usual way; a FallbackHandler class allows access to the failure.
Timeouts first
The order in which the annotations wrap each other follows a fixed rule: fallback outermost, then retry, then circuit breaker, then timeout, then bulkhead, with the bulkhead closest to the method. The effect is that each retry attempt gets its own timeout, the circuit breaker counts each attempt as a call, and the fallback catches the final failure. The timeout is therefore per attempt, and the total time is up to three attempts of 800 ms plus delays, about 2.6 seconds in the example. If your endpoint has a latency budget of two seconds, the numbers do not fit. Set them from the budget backwards, and check the arithmetic whenever you add a retry.
A timeout shorter than the dependency's normal worst-case latency causes failures that look like an outage. Base it on the measured 99th percentile, plus margin.
Retries need care
A retry is only safe for an operation that can be repeated. GET /price/42 is. POST /orders is not, unless it carries an idempotency key the server honours, as in idempotency keys. Restrict retryOn to exceptions that signal a transient problem, and use abortOn for those that never will succeed, such as a 400 mapped to WebApplicationException. The default retryOn is Exception, which retries on everything, including programming errors. The jitter parameter spreads retries so clients do not synchronise. Count retries as a metric; a rising retry rate warns of trouble before errors appear.
Circuit breaker behaviour
Choose the parameters from the traffic: requestVolumeThreshold of 4 with a low-traffic call opens the breaker on two failures, while the same setting on a service called a thousand times a second never fills a meaningful window. Set skipOn for exceptions that should not count as failures, like client errors. While the breaker is open, callers hit the fallback immediately, so the fallback must be cheap and must not call the same dependency. Each instance keeps its own breaker state; a cluster does not share it, which is normally acceptable.
Test the open state deliberately, as it is rarely exercised. A breaker that has never opened in a test may have a fallback that fails.
Async and the CDI proxy
The annotations work through CDI interception, so they apply only to calls that go through the bean's proxy. A method calling another method on this bypasses them, the same limit that affects Spring, see Spring proxies. Move the annotated method to another bean or call it through an injected reference. Methods returning Uni or CompletionStage are handled asynchronously, and the annotations apply to the returned future's outcome, with the timeout measured on completion. A blocking method on the event loop thread is a separate problem: annotate with @Blocking or move the work off the I/O thread. Mixing synchronous and asynchronous styles in one call chain makes the retry and timeout semantics hard to predict, so keep the annotated method's style consistent. For choosing a communication style, see synchronous versus asynchronous communication.
Observability
The extension integrates with Micrometer and OpenTelemetry. It exports metrics for invocations, retries, timeouts, circuit breaker state and bulkhead usage, under names like ft.invocations.total and ft.circuitbreaker.state.total. Put the circuit breaker state and the retry count on a dashboard, with alerts: a breaker that is open for minutes, or a retry rate above a few percent. Tracing shows which attempt of a retried call was slow. Setup for health, metrics and tracing is in Quarkus health, metrics and OpenTelemetry.
Where this does not apply
Annotations are a convenient default. Where you need fine control, such as a retry budget shared across a request or a policy chosen at run time, use the programmatic API. Fault tolerance does not repair a design that calls too many services in series. The specifications are at microprofile.io, and the extension is described in the Quarkus guide.


