An order detail endpoint looks simple in Java. Load the order, retrieve the customer profile, check inventory, fetch delivery information, and assemble the response.
With OpenFeign, each dependency can look like an ordinary interface call. That convenience is useful, but it can hide the fact that one page now depends on several networks, connection pools, and independently deployed services.
When the page becomes slow, increasing a timeout is rarely the best first step. The more useful questions are which calls the page actually needs, how much time and concurrency each dependency may consume, and what the application should do when a remote operation has an uncertain outcome.
This article explores an order-service design. The examples and calculations are illustrative and should not be treated as production benchmarks.
The case study uses an existing Java service that makes synchronous calls through Spring Cloud OpenFeign. Spring now considers the project feature-complete and recommends Spring HTTP Service Clients for new development. If you maintain an existing OpenFeign application, the reliability practices discussed here remain relevant. The same principles also apply to other HTTP client frameworks.
Remove unnecessary dependencies before tuning them
Suppose an order page calls the user, inventory, promotion, and delivery services on every request. Before optimizing those calls, examine what each returned value means.
The agreed price belongs to the order’s purchase history. Recalculating it from today’s promotion rules could change the appearance of an old transaction. The shipping address recorded for the order should not change merely because the customer edits their profile.
These values should usually come from the order’s stored snapshot. Current delivery progress is different: it changes after purchase and may justify a live lookup or an asynchronously maintained projection.
A current nickname or avatar might improve presentation, but its temporary absence should not necessarily prevent the customer from seeing the order.
Figure 1. Dependency importance follows the endpoint’s business purpose. Optional enrichment should not determine whether historical order facts remain available.
This classification is specific to the operation. Delivery information may be optional on an order summary but essential on a shipment-tracking endpoint. Inventory is not usually required to display a completed purchase, but reserving inventory is essential when accepting a new order.
Once those boundaries are clear, OpenFeign provides a compact way to express the remaining contracts:
@FeignClient(
name = "delivery-service",
contextId = "orderDeliveryClient"
)
public interface OrderDeliveryClient {
@GetMapping("/internal/shipments/{shipmentId}/summary")
ShipmentSummary getSummary(
@PathVariable("shipmentId") String shipmentId
);
}The application layer should decide whether a missing live summary can be replaced with an allowed historical value. The transport interface should not silently decide that every failure means “no shipment.”
The same reasoning applies to order lists. Calling a profile endpoint once for every row creates remote N+1 behavior. Collecting distinct identifiers and using a bounded batch endpoint can reduce repeated work. The batch contract still needs size limits, partial-result semantics, and a predictable response size.
Removing unnecessary calls reduces latency and failure exposure before any connection-pool tuning begins.
Give each dependency a budget, not just a read timeout
A remote call spends time in more places than the downstream controller. It may wait for a connection, resolve an address, establish a connection, negotiate TLS, wait for the response, and decode the payload.
The exact timeout coverage depends on the underlying HTTP client and configuration. A readTimeout should not be presented as a universal limit on the complete operation.
Start with the endpoint’s response budget. If a gateway stops waiting after a configured interval, the application should leave room for local processing and response delivery. Sequential dependencies consume cumulative time; independent calls executed concurrently contribute to the critical path, while also increasing simultaneous downstream demand.
Retries and backoff consume that same budget. Starting another attempt when almost no time remains creates work the caller is unlikely to use.
Static per-client timeout settings provide a baseline. A stricter end-to-end deadline requires deliberately propagating and enforcing the remaining budget; declaring a Feign interface does not implement that protocol automatically.
The application must also consider what happens when the caller stops waiting. Canceling a local future or reaching a gateway timeout does not prove that the downstream operation stopped. For a write, the server may still commit after the caller has received an error.
Connection-pool sizing should follow workload measurements rather than a large default number. Under stable conditions, a useful first approximation is:
Average in-flight requests
≈ arrival rate × average time in the system
500 requests/second × 0.1 second
≈ 50 in-flight requestsThat is an average concurrency estimate, not a recommendation to configure exactly fifty connections. Tail latency, queuing, connection reuse, and protocol behavior all affect the required capacity.
Fleet size matters too. A limit of one hundred concurrent calls per application instance can permit two thousand calls across twenty instances. Scaling callers may increase downstream pressure even when each individual instance appears healthy.
Use explicit limits for connection acquisition and outstanding work. Separate a slow reporting dependency from a latency-sensitive inventory dependency where they would otherwise compete for the same resources. A circuit breaker can reduce calls after it detects a failure pattern, but it does not replace a concurrency limit for work already admitted.
Retry an operation only when its meaning remains stable
Retries can recover from transient failures, but they can also multiply load during an outage. The first task is to identify where retries already exist: gateway, application code, Feign, load-balancer integration, or another client layer.
If several layers independently repeat the same operation, a modest policy at each layer can create many downstream attempts. Choose a clear retry owner and account for every attempt within the request budget.
Spring Cloud OpenFeign provides Retryer.NEVER_RETRY by default, unlike native Feign’s default behavior. Adding a Retryer changes that policy. Client-specific configuration should remain scoped to the intended client rather than accidentally becoming a global default through component scanning.
A bounded retry may be appropriate for a read after a recoverable connection failure. It is less useful when the downstream service is already overloaded. Rate-limit responses should follow the endpoint’s retry contract and remaining budget, rather than trigger immediate repetition.
Writes need an additional guarantee. Consider an inventory reservation:
@FeignClient(
name = "inventory-service",
contextId = "inventoryReservationClient"
)
public interface InventoryReservationClient {
@PostMapping("/internal/reservations")
ReservationResult reserve(
@RequestHeader("Idempotency-Key") String requestKey,
@RequestBody ReservationRequest request
);
}The header is only the interface contract. Correctness depends on what the inventory service does with it.
Suppose the inventory service reserves one unit and commits, but the response is lost. The order service sees a timeout. Generating a new key and trying again could create a second reservation.
The order workflow should retain the original operation key and resolve its outcome through a status query or controlled retry. The inventory service must bind that key to the original request and durable result.
Figure 2. A timeout creates uncertainty about the result. A stable operation key allows the workflow to recover without creating a second reservation.
Recording the key separately from the reservation creates another crash window. The deduplication decision, stock mutation, and reservation result need a coherent transaction and concurrency design.
The same key with a different SKU, quantity, or order identity must not silently return an unrelated earlier result. Key scope, request validation, and retention all belong to the API contract. A late retry after a reservation has expired must follow the documented lifecycle; it must not be mistaken for a fresh request to reserve again.
For longer recovery, preserve a pending order operation and reconcile it asynchronously. Returning “pending confirmation” is more accurate than declaring failure when the reservation may already exist—or declaring success because a fallback ran.
Make errors and fallback describe the business state
A fallback is a product decision expressed in code. It should preserve the distinction between absent data, unavailable data, and an operation whose outcome is unknown.
| Remote operation | Failure interpretation | Possible application response |
|---|---|---|
| Fetch an optional avatar | Enrichment unavailable | Omit the avatar |
| Fetch delivery progress | Live information unavailable | Show permitted last-known data with its age |
| Read inventory for display | Availability unknown | Ask the user to retry; do not invent zero stock |
| Reserve inventory | Reservation may or may not exist | Preserve the operation key and resolve the outcome |
| Redeem a coupon | Redemption is not confirmed | Do not report successful redemption |
An error decoder can translate a documented remote error into an application exception. HTTP status alone is sometimes insufficient. A 404 might represent a missing business resource, but it could also expose a wrong route or an incompatible deployment. A stable error body and operation-specific contract help distinguish those cases.
Avoid converting every exception into an empty object. That can make monitoring report successful calls while the application displays incorrect information.
Contract evolution deserves equal attention. Dedicated DTOs keep database entities from becoming accidental public APIs, but compatibility still requires testing. Adding an enum value may break an older consumer that cannot deserialize it. New fields are safe only when existing consumers tolerate them. Test representative old responses against the new client, and new responses against supported old clients.
Context propagation also needs boundaries. Forward only explicitly required headers, and derive tenant or identity context from trusted authentication handling. A browser-supplied tenant header should not become authoritative merely because an interceptor copied it.
For tracing, use the application’s configured instrumentation and propagation format. If work moves to another executor, verify that the necessary context follows it; a thread-local lookup alone may no longer return the intended values.
Choose one clearly documented resilience integration for the example. Sentinel and Spring Cloud CircuitBreaker are alternatives with their own dependencies and configuration. An enabled property does not establish that the required libraries, rules, and fallback types are correctly wired. A small integration test that forces a timeout or opens the circuit is more useful than a configuration block that merely looks plausible.
Diagnose the waiting before changing the timeout
Consider an illustrative trace in which an order endpoint takes about two seconds. The span labeled “inventory call” occupies most of that time.
That is a starting point, not proof that the inventory business logic is slow. The client span can include waiting before the request reaches the server, retries, and response handling.
Compare caller and downstream observations:
| Evidence | Question to investigate |
|---|---|
| Long client duration, little corresponding server time | Is the caller waiting for a connection, establishing one, retrying, or decoding? |
| One downstream instance is consistently slower | Does it have different resource pressure, GC behavior, or dependency health? |
| All downstream instances slow together | Is shared storage or another dependency saturated? |
| Attempts rise faster than incoming business requests | Are retries amplifying traffic? |
| Failures cluster after deployment | Are new connections, routing changes, or contract differences involved? |
Use attempt-level traces where possible. A single aggregate timer can hide two failed attempts followed by a successful one. Percentiles also need careful interpretation: the P99 values of individual services cannot simply be added to obtain the endpoint’s P99.
For a selected slow instance, inspect CPU, garbage collection, worker queues, database-pool waits, and slow queries before changing the client timeout. If load distribution is uneven, inspect the discovered instance set and actual routing decisions rather than assuming the registry is queried synchronously for every call.
Observe connection-pool pending, leased, and available counts alongside downstream capacity. Increasing the pool can move a queue from the caller into the database without improving completed throughput.
Feign logging can help, but payload logging is not a substitute for metrics and traces. Its logging level must be enabled on the relevant logger as well as configured within Feign. Full headers and bodies should be used cautiously because they can expose credentials or customer data and increase overhead. Keep high-cardinality identifiers in controlled logs and traces rather than turning every order ID into a metric label.
Verification should exercise the contract under failure:
- Delay an optional dependency and confirm the required order details still return within budget.
- Hold connections busy and confirm new calls encounter a bounded wait.
- Lose a reservation response after commit and verify recovery produces one reservation.
- Retry the same key with different parameters and verify rejection.
- Run mixed client and server versions and check unknown fields, enum values, and error responses.
- Restore a failed dependency gradually and confirm queued work and retries do not immediately overload it again.
For this order service, the useful improvement is not a larger timeout or a more elaborate Feign configuration. It is a smaller required dependency set, explicit resource budgets, stable write-operation identities, and errors that tell the truth about the business outcome.
OpenFeign makes the call easy to express. The surrounding design determines whether that call remains safe when it is slow, repeated, or interrupted.