Errors, retries and timeouts
A response with a status of 400 or more throws a FeignException subclass, so callers catch exactly the cases they handle. A Retryer tries again what may succeed later (connection errors, timeouts, Retry-After), call-timeout bounds a call as a whole, and a fallback answers when everything failed.
Why
Remote calls fail in ways local calls do not: the service is down, slow, overloaded, or answers with an error. Code that handles each case by hand around every call is long and inconsistent. With typed exceptions, a retry policy per client and a hard limit on time, the code around a call stays one try.
Example
// A missing book is not an error for the shop; anything else is.
Future<Book?> find(String isbn) async {
try {
return await catalog.find(isbn);
} on FeignNotFound {
return null;
} on FeignException catch (error) {
log.warning('catalog failed: ${error.status} ${error.responseBody}');
rethrow;
}
}
@Configuration()
class FeignSetup {
// Up to 3 attempts per call: pauses of 150 ms, then 225 ms.
@Bean()
Retryer retryer() => const DefaultRetryer(maxAttempts: 3);
// The catalog's 404 becomes the shop's own exception.
@Bean()
ErrorDecoder errorDecoder() => ShopErrors();
}
final class ShopErrors implements ErrorDecoder {
@override
Exception decode(String methodKey, HttpResponse response) =>
response.statusCode == 404
? BookNotFound(response.request!.url.path)
: const DefaultErrorDecoder().decode(methodKey, response);
}
spring.feign.client.config.catalog.call-timeout=5s
The exceptions
| Situation | Exception |
|---|---|
| 400, 401, 403, 404, 405, 406, 409, 410, 415, 422, 429 | FeignBadRequest, FeignUnauthorized, FeignForbidden, FeignNotFound, FeignMethodNotAllowed, FeignNotAcceptable, FeignConflict, FeignGone, FeignUnsupportedMediaType, FeignUnprocessableEntity, FeignTooManyRequests (all FeignClientException) |
| another 4xx | FeignClientException |
| 500, 501, 502, 503, 504 | FeignInternalServerError, FeignNotImplemented, FeignBadGateway, FeignServiceUnavailable, FeignGatewayTimeout (all FeignServerException) |
| another 5xx | FeignServerException |
a response with a Retry-After header |
RetryableException with the response's status |
| no response (connection failed, timeout) | RetryableException with status -1 |
call-timeout or the caller's deadline passed |
FeignCallTimeoutException, status -1 |
| a body that does not fit the return type | DecodeException |
| arguments that cannot be written into the request | EncodeException, before anything is sent |
A FeignException has status, message, request, responseBody, responseHeaders and cause. With dismiss404, a 404 gives null (or a ResponseEntity) instead; a void method still throws.
ErrorDecoder
An ErrorDecoder bean (or the error-decoder property, or a bean of the client's configuration classes) turns a response into an exception. It is called for every status outside 2xx, except a dismissed 404 and methods returning HttpResponse. Return a RetryableException to make an answer retryable, for example every 503.
Retries
As in Spring Cloud OpenFeign, nothing is retried by default. A Retryer bean retries only RetryableExceptions: connection errors, timeouts, and responses with a Retry-After header (in seconds or as an HTTP date). An error status alone is not retried. Every attempt is built again from the arguments and goes through the interceptors, so a token refreshed in the meantime reaches the retry.
DefaultRetryer works as Feign's Retryer.Default:
| Parameter | Default | Meaning |
|---|---|---|
maxAttempts |
5 |
Attempts in all, the first included. |
period |
100ms |
The base pause; the pause after attempt n is period × 1.5ⁿ (150 ms, 225 ms, 338 ms...). |
maxPeriod |
1s |
The longest pause. When the server sent Retry-After, it waits until then instead, still at most maxPeriod. |
A Retryer of your own implements nextDelay(attempt, error): the pause before the next attempt, or null to give up. Retryer.never never retries.
Timeouts
| Setting | Limits |
|---|---|
connect-timeout (10s, under default only) |
Each connection. |
read-timeout (60s) |
Each wait for data: for the response, then between two chunks of the body. Not the whole call. |
call-timeout (none) |
The whole call: every attempt, the pauses of the Retryer and the wait for the answer. |
call-timeout
read-timeout limits each wait, and a Retryer multiplies the attempts, so one call can take much longer than any timeout says. call-timeout is the time the call may take in all.
When it passes, the call throws a FeignCallTimeoutException (with the number of attempts, and whether the limit was the caller's deadline). It is never retried, because the time is gone: a pause that would end past the limit ends the call at once. The fallback still answers it. The connect and read timeouts of each attempt are capped by what remains, so a read-timeout of 60 seconds cannot outlast a call-timeout of 5.
The caller's deadline
A call made while a web request is handled (server.request-timeout of the web starter), or inside RequestDeadline.run(...), has a second limit: the deadline of the code that makes it. The call is limited by the earlier of the two, so it never outlives its request. The interceptors run under the same limit.
// At most 2 seconds for the whole checkout, whatever the clients do.
final order = await RequestDeadline.run(const Duration(seconds: 2), () async {
final stock = await warehouse.reserve(basket);
return payments.charge(basket, stock);
});
Fallback
A fallback answers instead of the remote service when a call fails, for example with cached or placeholder data. It is a bean class that implements the same interface:
@FeignClient('motd', url: r'${motd.url}', fallback: OfflineMotd)
abstract interface class MotdApi {
@GetMapping('/motd')
Future<String> messageOfTheDay();
}
// What the app shows while the service is unreachable.
@Component()
class OfflineMotd implements MotdApi {
@override
Future<String> messageOfTheDay() async => 'offline, try later';
}
- The fallback answers every failure, a 404 too, after the retries.
- The generated client is
@Primary(unless@FeignClient(primary: false)), so injectingMotdApigives the client, not the fallback. - There is no circuit breaker and no
FallbackFactoryyet.
In Spring (Java)
@Bean
Retryer retryer() { return new Retryer.Default(100, 1000, 3); }
The exceptions, ErrorDecoder and Retryer.Default behave as in Feign. call-timeout and the caller's deadline are additions: Spring Cloud OpenFeign limits only the connect and the read of each attempt.