
# 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

```dart
// 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;
  }
}
```

```dart
@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);
}
```

```properties
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 `RetryableException`s: 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.

```dart
// 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:

```dart
@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 injecting `MotdApi` gives the client, not the fallback.
- There is no circuit breaker and no `FallbackFactory` yet.

## In Spring (Java)

```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.

## See also

- [Configuration](configuration.md)
- [Interceptors](interceptors.md)
- [Timeouts in the web starter](../spring-boot-starter-web/server/timeouts.md)
