@FeignClient(name = "catalog", url = "${clients.catalog.base-url}")
public interface CatalogFeignClient {

    @GetMapping("/v1/products/{id}")
    ProductView getProduct(@PathVariable("id") String id);
}

ProductView product = catalogFeignClient.getProduct("p-123");

latency
partial failure
timeouts
retry ambiguity
unknown outcome
status mapping
serialization failure
connection pool pressure
load balancing behavior
observability requirements
contract drift

Java interface
  + annotations describing HTTP mapping
  + encoder for request body
  + decoder for response body
  + contract parser
  + HTTP transport client
  + error decoder
  + retryer
  + request interceptors
  + optional load balancer / circuit breaker integration

@FeignClient interface
  -> Spring proxy bean
  -> Feign invocation handler
  -> request template
  -> encoder/interceptors
  -> HTTP client
  -> response decoder/error decoder
  -> Java return value or exception

catalog lookup
pricing quote
customer profile read
policy evaluation request
case status query
small command with idempotency key

public CheckoutView checkout(CheckoutRequest request) {
    Customer customer = customerClient.getCustomer(request.customerId());
    Price price = pricingClient.quote(request.items());
    Inventory inventory = inventoryClient.reserve(request.items());
    Payment payment = paymentClient.authorize(request.payment());

    return CheckoutView.of(customer, price, inventory, payment);
}

checkout
  -> customer
  -> pricing
  -> inventory
  -> payment

latency is cumulative if sequential
any dependency can fail
retry can duplicate commands
partial side effects can occur
thread is blocked while waiting
caller capacity is consumed
exception type may hide remote semantics

Customer customer = customerGateway.fetchCustomer(request.customerId());
Price price = pricingGateway.quote(request.items());
InventoryReservation reservation = inventoryGateway.reserveWithIdempotencyKey(command);

customerRepository.findById(id)

customerServiceClient.getCustomer(id)
customerGateway.fetchCustomer(id)
remoteCustomerClient.getCustomer(id)

@FeignClient(
    name = "catalogClient",
    url = "${clients.catalog.base-url}",
    configuration = CatalogFeignConfiguration.class
)
public interface CatalogFeignClient {

    @GetMapping(value = "/v1/products/{id}", produces = MediaType.APPLICATION_JSON_VALUE)
    ProductView getProduct(@PathVariable("id") String id);
}

@Service
public class ProductApplicationService {

    private final CatalogFeignClient catalog;

    public ProductApplicationService(CatalogFeignClient catalog) {
        this.catalog = catalog;
    }

    public ProductView getProduct(String id) {
        return catalog.getProduct(id);
    }
}

connect timeout
read timeout
retry policy
error decoder
request interceptor
logger level
underlying HTTP client
observability
idempotency propagation
status-code mapping

controllers call Feign clients directly
services call Feign clients directly
scheduled jobs call Feign clients directly
event consumers call Feign clients directly

public interface CatalogGateway {
    ProductView getProduct(ProductId id);
    Optional<ProductView> findProduct(ProductId id);
}

@Component
public final class FeignCatalogGateway implements CatalogGateway {

    private final CatalogFeignClient client;

    public FeignCatalogGateway(CatalogFeignClient client) {
        this.client = client;
    }

    @Override
    public ProductView getProduct(ProductId id) {
        try {
            return client.getProduct(id.value());
        } catch (ProductNotFoundRemoteException e) {
            throw new ProductNotFoundException(id, e);
        } catch (CatalogRemoteUnavailableException e) {
            throw new CatalogUnavailableException(id, e);
        }
    }

    @Override
    public Optional<ProductView> findProduct(ProductId id) {
        try {
            return Optional.of(client.getProduct(id.value()));
        } catch (ProductNotFoundRemoteException e) {
            return Optional.empty();
        }
    }
}

@Configuration
public class CatalogFeignConfiguration {

    @Bean
    public Request.Options catalogRequestOptions() {
        return new Request.Options(
            200, TimeUnit.MILLISECONDS,  // connect timeout
            500, TimeUnit.MILLISECONDS,  // read timeout
            true                         // follow redirects
        );
    }

    @Bean
    public Retryer catalogRetryer() {
        return Retryer.NEVER_RETRY;
    }

    @Bean
    public ErrorDecoder catalogErrorDecoder(ObjectMapper objectMapper) {
        return new CatalogErrorDecoder(objectMapper);
    }

    @Bean
    public RequestInterceptor correlationHeadersInterceptor() {
        return template -> {
            RequestContext ctx = RequestContextHolder.currentOrAnonymous();
            template.header("X-Request-Id", ctx.requestId());
            template.header("X-Correlation-Id", ctx.correlationId());
        };
    }
}

connect timeout
read timeout

caller deadline
retry budget
connection pool acquisition behavior
DNS behavior
TLS handshake behavior
load balancer behavior
proxy/gateway timeout
server timeout

operation criticality
user-facing SLO
downstream latency distribution
number of attempts
caller remaining budget
fallback availability

User request SLO: 1000 ms
Checkout service local work: 150 ms
Remaining for downstream required calls: 850 ms
Catalog lookup budget: 200 ms
Pricing quote budget: 250 ms
Inventory reservation budget: 300 ms
Safety margin: 100 ms

@Bean
public Retryer retryer() {
    return Retryer.NEVER_RETRY;
}

@Bean
public Retryer catalogLookupRetryer() {
    return new Retryer.Default(
        50,                    // initial period in ms
        TimeUnit.MILLISECONDS.toMillis(200),
        2                      // max attempts
    );
}

connect timeout before request was sent
connection refused
transient 503
429 if policy permits and budget remains
idempotent GET
idempotent command with idempotency key

400 validation error
401/403 auth/authz failure
404 normal absence
409 business conflict
422 semantic validation failure
non-idempotent POST without idempotency key
unknown outcome after command may have been committed

public final class CatalogErrorDecoder implements ErrorDecoder {

    private final ObjectMapper objectMapper;

    public CatalogErrorDecoder(ObjectMapper objectMapper) {
        this.objectMapper = objectMapper;
    }

    @Override
    public Exception decode(String methodKey, Response response) {
        RemoteProblem problem = readProblem(response);
        int status = response.status();

        return switch (status) {
            case 400, 422 -> new CatalogValidationRemoteException(problem, methodKey);
            case 404 -> new ProductNotFoundRemoteException(problem, methodKey);
            case 409 -> new CatalogConflictRemoteException(problem, methodKey);
            case 429 -> new CatalogThrottledRemoteException(problem, methodKey, retryAfter(response));
            case 503 -> new CatalogRemoteUnavailableException(problem, methodKey, true);
            default -> {
                if (status >= 500) {
                    yield new CatalogRemoteUnavailableException(problem, methodKey, true);
                }
                yield new CatalogProtocolException(problem, methodKey, status);
            }
        };
    }

    private RemoteProblem readProblem(Response response) {
        if (response.body() == null) {
            return RemoteProblem.unknown();
        }

        try (InputStream input = response.body().asInputStream()) {
            byte[] capped = input.readNBytes(16 * 1024);
            return objectMapper.readValue(capped, RemoteProblem.class);
        } catch (Exception ignored) {
            return RemoteProblem.unknown();
        }
    }

    private Optional<Duration> retryAfter(Response response) {
        Collection<String> values = response.headers().getOrDefault("Retry-After", List.of());
        return values.stream().findFirst().flatMap(RetryAfterParser::parse);
    }
}

cap error body size
handle missing body
handle invalid JSON
preserve status code
preserve remote error code
include method key / operation
mark retryability explicitly
do not log raw body by default

if (response.status() == 503 && isIdempotent(methodKey)) {
    return new RetryableException(
        response.status(),
        "catalog unavailable",
        response.request().httpMethod(),
        cause,
        retryAfterInstant,
        response.request()
    );
}

Feign retryer disabled by default
resilience policy applied in gateway layer
retry classifier uses operation metadata
idempotency key required for retryable commands
retry budget enforced per request

What happens if the request times out after the server commits?

@PostMapping("/v1/reservations")
ReservationView reserve(
    @RequestHeader("Idempotency-Key") String idempotencyKey,
    @RequestBody ReservationCommand command
);

public Reservation reserve(ReserveInventoryCommand command) {
    String key = idempotencyKeyFactory.forCommand(command.commandId());

    try {
        ReservationView view = client.reserve(key, ReservationCommandDto.from(command));
        return ReservationMapper.toDomain(view);
    } catch (InventoryRemoteUnavailableException e) {
        throw new ReservationOutcomeUnknownException(command.commandId(), e);
    }
}

outcome unknown

failed

@Bean
RequestInterceptor requestContextInterceptor() {
    return template -> {
        RequestContext ctx = RequestContextHolder.currentOrAnonymous();

        template.header("X-Request-Id", ctx.requestId());
        template.header("X-Correlation-Id", ctx.correlationId());
        template.header("X-Deadline-Ms", Long.toString(ctx.deadlineEpochMillis()));

        ctx.idempotencyKey().ifPresent(key ->
            template.header("Idempotency-Key", key)
        );
    };
}

hidden remote calls
dynamic blocking token refresh without timeout
large payload mutation
random retry logic
application-specific business branching

propagate only allowed identity/security context
never blindly forward all inbound headers
separate end-user identity from service identity
redact credentials in logs
control token audience and scope
keep auth failure distinct from dependency failure

@Bean
RequestInterceptor serviceTokenInterceptor(ServiceTokenProvider tokenProvider) {
    return template -> template.header(
        HttpHeaders.AUTHORIZATION,
        "Bearer " + tokenProvider.tokenForAudience("catalog")
    );
}

connection pooling
TLS behavior
HTTP version support
timeout precision
proxy support
metrics availability
compression behavior
resource cleanup

@FeignClient(name = "catalog", url = "${clients.catalog.base-url}")

@FeignClient(name = "catalog")

Who resolves service instances?
How often is discovery refreshed?
What happens when an instance is unhealthy?
Is load balancing client-side, gateway-side, or mesh-side?
Are retries aware of instance selection?
Can retry hit a different instance?
How are zones/locality handled?

Feign retry
+ client-side load balancer retry
+ service mesh retry
+ gateway retry
= retry amplification

Spring Cloud circuit breaker integration
Resilience4j around gateway method
service mesh outlier detection
manual wrapper policy

public ProductView getProduct(ProductId id) {
    Supplier<ProductView> supplier = CircuitBreaker.decorateSupplier(
        catalogCircuitBreaker,
        () -> client.getProduct(id.value())
    );

    try {
        return supplier.get();
    } catch (CallNotPermittedException e) {
        throw new CatalogUnavailableException("catalog circuit open", e);
    }
}

optional recommendation returns empty recommendation list

payment authorization returns approved
inventory reservation returns successful
compliance screening returns clear

Is stale data acceptable?
Is missing data acceptable?
Will fallback violate compliance or accounting?
Will the user see degraded result?
How is fallback measured?
How do we avoid hiding dependency incidents?

PII leakage
credential leakage
large log volume
latency impact
sensitive business data exposure
binary/body corruption in logs

operation=catalog.getProduct
peer.service=catalog
status=503
latency_ms=242
attempt=1
retryable=true
request_id=...
correlation_id=...

enable temporarily
sample aggressively
redact sensitive fields
cap size
restrict environment
ensure audit trail

operation
peer.service
http.method
http.route
status code
latency
exception class
retry count
circuit breaker state
fallback used
timeout vs remote error vs local rejection

Which Feign client is causing tail latency?
Which downstream route returns most 5xx?
Are timeouts increasing?
Are retries amplifying load?
Are circuit breakers opening?
Are fallbacks hiding incidents?
Which caller triggered downstream overload?

/v1/products/p-123
/v1/products/p-456

/v1/products/{id}

ProductView getProduct(String id);

sealed interface ProductLookupResult permits ProductFound, ProductMissing, ProductLookupUnavailable {}

ProductView getProduct(String id);

public ProductLookupResult findProduct(ProductId id) {
    try {
        return new ProductFound(client.getProduct(id.value()));
    } catch (ProductNotFoundRemoteException e) {
        return new ProductMissing(id);
    } catch (CatalogRemoteUnavailableException e) {
        return new ProductLookupUnavailable(id, e.retryable());
    }
}

Accept
Content-Type
Authorization or service identity token
X-Request-Id
X-Correlation-Id
traceparent
tracestate
baggage, if allowed
Idempotency-Key for commands
X-Deadline-Ms or equivalent deadline metadata

all inbound headers blindly
browser cookies to internal services
hop-by-hop headers
untrusted x-forwarded-* values
large baggage values
PII-bearing custom headers

path changed
query parameter renamed
field removed
enum value added
error shape changed
status code changed
content type changed
pagination semantics changed

OpenAPI contract published by provider
consumer-side contract tests
generated clients when appropriate
backward compatibility rules
schema diff in CI
staging smoke tests against real provider
versioning policy

huge generated surface area
transport policy scattered in generated code
awkward exception model
inconsistent date/time mapping
regeneration churn
weak domain boundary
hard-to-review diffs

generated low-level client
wrapped by stable domain gateway
application depends only on gateway

max concurrent inbound requests
x downstream calls per request
x timeout duration
= thread and connection pressure

short timeouts
bulkheads
connection pool limits
rate limits
bounded queues
circuit breakers
load shedding
async/reactive only where actually needed

public ProductView getProduct(ProductId id) {
    Supplier<ProductView> supplier = Bulkhead.decorateSupplier(
        catalogBulkhead,
        () -> client.getProduct(id.value())
    );

    try {
        return supplier.get();
    } catch (BulkheadFullException e) {
        throw new CatalogUnavailableException("catalog bulkhead full", e);
    }
}

catalog read pool
pricing quote pool
inventory command pool
payment command pool
optional recommendation pool

public record RemoteProblem(
    String type,
    String title,
    int status,
    String detail,
    String instance,
    String code,
    String correlationId
) {
    static RemoteProblem unknown() {
        return new RemoteProblem(
            "about:blank",
            "Unknown remote error",
            0,
            null,
            null,
            "unknown",
            null
        );
    }
}

RemoteValidationException
RemoteConflictException
RemoteNotFoundException
RemoteThrottledException
RemoteUnavailableException
RemoteProtocolException

method
path
query parameters
headers
body
content type
accept type

GET /v1/products/p-1
Accept: application/json
X-Correlation-Id present
Authorization present

404 problem => ProductNotFoundRemoteException
409 problem => CatalogConflictRemoteException
429 => throttled and retry metadata preserved
503 => unavailable and retryable if policy allows
malformed error body => protocol exception with safe fallback problem
large error body => capped

not found maps to Optional.empty
unavailable maps to dependency unavailable result
timeout maps to outcome unknown for commands
non-idempotent command is not retried
fallback only for optional dependency

@FeignClient(
    name = "catalogClient",
    url = "${clients.catalog.base-url}",
    configuration = CatalogFeignConfiguration.class
)
public interface CatalogFeignClient {

    @GetMapping(value = "/v1/products/{id}", produces = MediaType.APPLICATION_JSON_VALUE)
    ProductView getProduct(
        @PathVariable("id") String id
    );

    @PostMapping(
        value = "/v1/product-reservations",
        consumes = MediaType.APPLICATION_JSON_VALUE,
        produces = MediaType.APPLICATION_JSON_VALUE
    )
    ReservationView reserveProduct(
        @RequestHeader("Idempotency-Key") String idempotencyKey,
        @RequestBody ReserveProductRequest request
    );
}

@Configuration
public class CatalogFeignConfiguration {

    @Bean
    Request.Options requestOptions() {
        return new Request.Options(
            200, TimeUnit.MILLISECONDS,
            500, TimeUnit.MILLISECONDS,
            true
        );
    }

    @Bean
    Retryer retryer() {
        return Retryer.NEVER_RETRY;
    }

    @Bean
    ErrorDecoder errorDecoder(ObjectMapper objectMapper) {
        return new CatalogErrorDecoder(objectMapper);
    }

    @Bean
    RequestInterceptor requestContextInterceptor(ServiceTokenProvider tokenProvider) {
        return template -> {
            RequestContext ctx = RequestContextHolder.currentOrAnonymous();
            template.header(HttpHeaders.AUTHORIZATION,
                "Bearer " + tokenProvider.tokenForAudience("catalog"));
            template.header("X-Request-Id", ctx.requestId());
            template.header("X-Correlation-Id", ctx.correlationId());
            template.header("X-Deadline-Ms", Long.toString(ctx.deadlineEpochMillis()));
        };
    }

    @Bean
    Logger.Level feignLoggerLevel() {
        return Logger.Level.BASIC;
    }
}

@Component
public final class CatalogGateway {

    private final CatalogFeignClient client;
    private final CircuitBreaker circuitBreaker;
    private final Bulkhead bulkhead;

    public CatalogGateway(
        CatalogFeignClient client,
        CircuitBreakerRegistry circuitBreakers,
        BulkheadRegistry bulkheads
    ) {
        this.client = client;
        this.circuitBreaker = circuitBreakers.circuitBreaker("catalog");
        this.bulkhead = bulkheads.bulkhead("catalog");
    }

    public Optional<ProductView> findProduct(ProductId id) {
        Supplier<ProductView> supplier = () -> client.getProduct(id.value());

        Supplier<ProductView> protectedSupplier = Decorators.ofSupplier(supplier)
            .withBulkhead(bulkhead)
            .withCircuitBreaker(circuitBreaker)
            .decorate();

        try {
            return Optional.of(protectedSupplier.get());
        } catch (ProductNotFoundRemoteException e) {
            return Optional.empty();
        } catch (CallNotPermittedException | BulkheadFullException e) {
            throw new CatalogUnavailableException("catalog protected call rejected", e);
        } catch (CatalogRemoteUnavailableException e) {
            throw new CatalogUnavailableException("catalog unavailable", e);
        }
    }

    public ReservationView reserveProduct(ReserveProductCommand command) {
        String key = IdempotencyKeys.forCommand(command.commandId());

        try {
            return client.reserveProduct(key, ReserveProductRequest.from(command));
        } catch (CatalogRemoteUnavailableException e) {
            throw new ReservationOutcomeUnknownException(command.commandId(), e);
        }
    }
}

[ ] Feign interface is not exposed across application layers
[ ] gateway wrapper maps remote semantics into domain semantics
[ ] connect timeout configured
[ ] read timeout configured
[ ] retry disabled by default or explicitly justified
[ ] retries only for safe/idempotent operations
[ ] idempotency key used for retryable commands
[ ] ErrorDecoder maps status codes explicitly
[ ] error body parsing is capped and safe
[ ] correlation/trace headers propagated via allowlist
[ ] Authorization propagation is intentional
[ ] logging level avoids body/PII leakage
[ ] route metrics use templates, not raw ids
[ ] circuit breaker/bulkhead policy exists for critical dependencies
[ ] fallback is domain-approved, not library convenience
[ ] generated clients are wrapped if used
[ ] tests cover request mapping and error mapping
[ ] service discovery/load balancer retry interaction is understood
[ ] mesh/gateway retry does not duplicate Feign retry

Declarative syntax must not erase remote-call semantics.

HTTP API is stable
communication is synchronous
request/response shape is simple
team wants interface-based clients
policy is centralized per client

streaming is needed
reactive composition is needed
command outcome ambiguity matters
fine-grained response handling dominates
fallback would be semantically dangerous

application -> Feign proxy -> remote service

application -> domain gateway -> Feign proxy -> remote service