
# Configuration

Each client is configured under its name (`@FeignClient('catalog')`) in `spring.feign.client.config.catalog.*`. The name `default` applies to every client, and a client's own setting wins. The keys are Spring Cloud OpenFeign's, under `spring.feign` instead of `spring.cloud.openfeign`. `@FeignClient` attributes and per-client configuration classes complete it.

## Why

Timeouts, logging and credentials differ between services and environments: a slow reporting service needs a long read timeout, a payment service needs retries and its own account, development needs full logs. Properties change these without a build, and the `default` block keeps the common values in one place.

## Example

```properties
# lib/resources/application.properties
spring.feign.client.config.default.read-timeout=10s
spring.feign.client.config.default.connect-timeout=2s
spring.feign.client.config.default.call-timeout=15s
spring.feign.client.config.default.sensitive-headers=X-Api-Key

spring.feign.client.config.catalog.url=https://api.neon.books
spring.feign.client.config.catalog.logger-level=basic
spring.feign.client.config.catalog.dismiss404=true
spring.feign.client.config.catalog.default-request-headers.X-Shop=neon
spring.feign.client.config.catalog.default-query-parameters.lang=en
spring.feign.client.config.catalog.follow-redirects=false
spring.feign.client.config.catalog.retryer=catalogRetryer
spring.feign.client.config.catalog.error-decoder=ShopErrors
spring.feign.client.config.catalog.request-interceptors[0]=requestIds

spring.feign.client.decode-slash=false
```

```dart
// The catalog needs its own account and a few retries.
@FeignClient('catalog', url: r'${catalog.url}', configuration: [CatalogFeignConfig])
abstract interface class CatalogClient {
  @GetMapping('/books/{isbn}')
  Future<Book> find(@PathVariable() String isbn);
}

@Configuration()
class CatalogFeignConfig {
  @Bean()
  Retryer catalogRetryer() => const DefaultRetryer(maxAttempts: 3);

  @Bean()
  RequestInterceptor catalogAuth() => BasicAuthRequestInterceptor('shop', 's3cret');
}
```

## Client settings

Each key is `spring.feign.client.config.<name>.<key>`; the full table with types is on [All properties](properties.md).

| Key | Default | Meaning |
|---|---|---|
| `url` | none | The base URL when `@FeignClient(url:)` is empty; `http://` is added when the scheme is missing. `${...}` placeholders are allowed. |
| `read-timeout` | `60s` | The longest wait for the response, then between two chunks of the body; not a limit for the whole call. `0` for none. |
| `connect-timeout` | `10s` | Under `default` only: the connect timeout of the transport all clients share. `0` for none. |
| `call-timeout` | none | The longest one call may take in all, retries and pauses included. |
| `logger-level` | `none` | `none`, `basic`, `headers`, `full` (see [Logging](logging.md)). |
| `dismiss404` | `false` | A 404 gives `null` (or a `ResponseEntity`) instead of an exception; `void` methods still throw. |
| `default-request-headers.<Name>` | none | A header added to every request that has none of that name once the interceptors ran. A comma list or an indexed list gives several values. |
| `default-query-parameters.<name>` | none | The same for query parameters. The URL with its query is logged and in exception messages: prefer a header for a secret. |
| `follow-redirects` | `true` | With `false`, a 3xx answer is an error status. |
| `retryer` | none (never retries) | A `Retryer` bean, by bean name or by a class name matching exactly one bean. |
| `error-decoder` | `DefaultErrorDecoder` | An `ErrorDecoder` bean, the same way. |
| `request-interceptors` | none | More `RequestInterceptor` beans, by name: `default`'s first, then the client's. |
| `sensitive-headers` | none | More headers masked as `***` in the logs: `default`'s, then the client's. |
| `event-stream.reconnect`, `.reconnect-delay`, `.max-attempts` | `true`, `3s`, no limit | Server-sent events (see [Server-sent events](server-sent-events.md)). |

And one key for all clients: `spring.feign.client.decode-slash` (`true`): a `/` in a `@PathVariable` value stays a `/`; `false` sends it as `%2F`.

### How values combine

- A client's key wins over `default`'s.
- `default-request-headers` and `default-query-parameters` of a client add to those of `default`, and win for the same name.
- `request-interceptors` and `sensitive-headers` add up: `default`'s, then the client's.
- The on/off keys (`dismiss404`, `follow-redirects`, `event-stream.reconnect`, `decode-slash`) take `true` / `false` in any case, and also `on` / `off`, `yes` / `no`, `1` / `0`. Another value stops the application with an error naming the key.
- `spring.cloud.openfeign.*` keys stop the start and name the new key.

## @FeignClient

| Attribute | Default | Meaning |
|---|---|---|
| `name` (positional) | | The service's name: the configuration key and the `clientName` interceptors see. |
| `url` | none | The base URL; wins over the `url` property. `${...}` placeholders are resolved. |
| `path` | `''` | Put before every method's path. |
| `contextId` | the name | The configuration key instead of the name (`...config.catalog-admin.*`), for two clients of one service with different settings. |
| `qualifiers` | `[]` | More names that select the client bean with `@Qualifier('books')`. |
| `primary` | `true` | Whether the client bean is `@Primary`. |
| `dismiss404` | `false` | The same as the `dismiss404` property. |
| `configuration` | `[]` | `@Configuration()` classes whose beans apply to this client only. |
| `fallback` | none | A bean class implementing the interface, which answers when a call fails (see [Errors, retries and timeouts](errors-and-retries.md)). |

## Per-client beans

`@FeignClient(configuration:)` lists classes whose `Retryer`, `ErrorDecoder` and `RequestInterceptor` beans configure that client only. A listed class must be a `@Configuration()` bean; the application stops otherwise. Its beans never reach the other clients.

For each client the starter picks:

- **Retryer and error decoder:** the `retryer` / `error-decoder` property when set; else the bean of the client's configuration classes; else the application's bean; else no retries and the `DefaultErrorDecoder`. Two candidate beans at one level need one of them to be `@Primary`.
- **Interceptors:** the application's `RequestInterceptor` beans and those of the client's configuration classes, all together in `@Order`; then the beans the `request-interceptors` property names. The property adds to the beans; a bean that is both runs once.

## In Spring (Java)

```yaml
spring:
  cloud:
    openfeign:
      client:
        config:
          default:
            read-timeout: 10000
          catalog:
            logger-level: basic
```

The keys are Spring Cloud OpenFeign's under `spring.feign`. `connect-timeout` is one setting for all clients; `call-timeout` and `sensitive-headers` are additions. The `retryer`, `error-decoder` and `request-interceptors` properties name beans (Spring creates the class when there is no bean). Configuration classes are ordinary beans kept away from the other clients, not child contexts; only `Retryer`, `ErrorDecoder` and `RequestInterceptor` are per client.

## See also

- [All properties](properties.md)
- [Errors, retries and timeouts](errors-and-retries.md)
- [Interceptors](interceptors.md)
