To build resilient applications on commercetools Composable Commerce, it's essential to configure timeouts and retries correctly. This guide explains timeout and retry principles, outlines best practices, and provides recommended timeout values based on use cases performed with Composable Commerce APIs.
Why timeouts and retries matter
Network latency, transient failures, and service disruptions are inevitable. Without proper timeout and retry mechanisms, applications are vulnerable to errors and disruptions, leading to degraded performance and poor user experience. Implementing robust timeout and retry strategies ensures that applications can gracefully handle these challenges and continue functioning effectively.
By implementing the strategies recommended in this guide, you can:
- Prevent operations from hanging indefinitely, which can lead to resource exhaustion.
- Improve user experience by failing fast and enabling error recovery or retry behavior.
- Reduce the impact of intermittent network issues and temporary service slowdowns.
- Improve fault tolerance in distributed systems and asynchronous workflows.
- Maintain responsiveness by retrying after a designated timeout instead of waiting indefinitely.
Applications should avoid indefinite waits by setting a maximum timeout and initiating retries when responses exceed it. This ensures responsiveness and reduces user-perceived latency.
Assumptions and context
Recommended timeout values
Timeout and retry behavior should be service-aware and dynamically configurable. Avoid applying a single hardcoded timeout across all API calls. Configure timeouts based on use case instead. Use dedicated API Clients for your use cases, give each API Client its own timeout and retry configuration.
The maximum duration for requests to Composable Commerce is 60 seconds. Complex queries to fetch multiple resources will timeout after 20 seconds of API processing.
GET requests
Recommended timeout value and retry policy:
- Resource lookups by ID or key, 1 second with exponential backoff.
- Resource queries with predicate, up to 5 seconds, immediate retries for transient failures.
POST requests
POST requests on most Composable Commerce APIs lead to write operations (create or update) on resources in your Project and involve integrity checks and potentially further validations before the new state is persisted.
POST requests to our Search APIs are read methods and should be treated like GET requests in your timeout and retry configuration.
Recommended timeout values for creating and updating:
- simple resources, like Inventory Entry and Standalone Price: 2 - 5 seconds
- complex resources, such as Carts, Orders, and Products: 5 - 10 seconds
Choose values based on the slowest observed performance in production, with some additional overhead. Ensure your application accounts for possible duplicate writes or version conflicts, retry update requests only if an update is still required. Keep in mind that requests can still succeed after the client timed out.
Retry policies
Exponential backoff
Use delays before retrying the next request. Recommended default is 200 ms. A good practice is to implement exponential backoff and gradually increases the time delay between successive retry attempts to reduce network congestion and increase resilience during transient failures.
Concurrent Modification error
message of the 409 Concurrent Modification error is the same as the actual version, a previous request is still in progress.
Fetch the resource after 1 second delay in this case to get the updated version of the resource.Maximum Retry Attempts
Define a maximum number of retry attempts to avoid indefinite retries, ensuring that the application gracefully handles persistent failures. A good default is 5 retries for the same error event, though 3 retries is sufficient for most use cases. Use exponential backoff delays before retrying the next request.
Logging and monitoring
Effective timeout and retry strategies require visibility into their behavior. Integrate:
- Structured logging for retry attempts, response times, and error types.
- Correlation IDs to trace request flow and isolate timeouts.
- Application performance monitoring to detect latency anomalies.
- Alerts for retry storms or repeated failures.
Use this telemetry to refine timeout values and retry policies over time.
Summary
Timeouts and retries are essential tools for building robust integrations with Composable Commerce. To ensure the highest reliability:
- Use short, targeted timeouts wherever possible.
- Do not set timeouts longer than 60 seconds.
- Avoid applying the same timeout globally. Configure timeouts based on use case and system architecture.
- Use exponential backoff delays before retrying the request.
- Define a maximum number of retry attempts.
- Monitor and log all retry and timeout behavior for observability and tuning.
- Adjust retry behavior based on observed performance in production.
| Request type | Timeout | Retry strategy |
|---|---|---|
GET a small resource by identifier | 1 second | Retry with exponential backoff |
GET a filtered collection | 5 seconds | Retry immediately, without delay |
POST (Create/Update) | 10 seconds | Retry with exponential backoff (if applicable) |
By adopting these practices, your application can better tolerate latency, maintain responsiveness, and handle failure better.