# Error handling through timeout and retries Best practices for handling errors with timeouts and retries. To build resilient applications, 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 commercetools 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 This guidance assumes your application design follows our [performance tips](https://docs.commercetools.com/api/performance-tips.md). Those cover aspects like concurrency, API request planning, and caching of API responses. But this guide focuses on the strategies you can implement in the HTTP client itself. We highly recommend implementing your applications with our [SDKs](https://docs.commercetools.com/api/dev-tooling.md) that provide configuration parameters for timeouts and retries. For example in the [Java SDK](https://docs.commercetools.com/api/dev-tooling/java-sdk-middleware.md#policymiddleware) and in the [TypeScript SDK](https://docs.commercetools.com/api/dev-tooling/ts-sdk-best-practices.md#configure-retries-and-timeouts). We also assume that you constantly [log and monitor](https://docs.commercetools.com/api/error-handling.md#logging-and-monitoring) API usage of your application on your side. This document recommends best practices for the APIs that manage resources in a Project directly. If your application uses the Import API, find some best practices in the [dedicated page](https://docs.commercetools.com/api/import-export/best-practices.md). If you orchestrate third-party APIs as well, check their recommendations and take their latencies into account also. ## 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 is 60 seconds. Complex queries to fetch multiple resources will timeout after 20 seconds of API processing. ### GET requests While response times are consistently low, small numbers of outlier requests can sometimes exceed this window. For complex queries that consistently take longer than 2 seconds, review to apply [best practices](https://docs.commercetools.com/api/predicates/query.md#performance-considerations). Recommended timeout value and retry policy: - Resource lookups by ID or key, 1 second with [exponential backoff](https://docs.commercetools.com/api/error-handling.md#exponential-backoff). - Resource queries with predicate, up to 5 seconds, immediate retries for transient failures. ### POST requests POST requests on most 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 If your POST request is forwarded to an [API Extension](https://docs.commercetools.com/api/projects/api-extensions.md), its latency should be taken into account. Consider an example in which a Cart update action triggers an API Extension that calls a Payment Service Provider, and the p99 latency including transfer for this is 8 seconds. If we say we would give the update action alone a 5 seconds timeout, setting a timeout of 11 seconds would be recommended to make these requests robust in the rare case of slower performance. 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 Your application must gracefully handle [502 Bad Gateway](https://docs.commercetools.com/api/errors.md#502-bad-gateway) and [503 Service Unavailable](https://docs.commercetools.com/api/errors.md#503-service-unavailable) errors. Enable retries on network errors and selected 5xx statusCode responses. Implement a backoff strategy, progressively increasing the delay between retries. [Load test](https://docs.commercetools.com/api/load-testing.md) your application to evaluate your retry strategy. ### 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 If a [409 ConcurrentModification](https://docs.commercetools.com/api/errors.md#concurrentmodification) error is returned on retry, check the newest state of the resource and retry only if the resource update is still required. If the expected version in the `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. The [Java SDK](https://docs.commercetools.com/api/dev-tooling/java-sdk-middleware.md#concurrentmodificationmiddleware) as well as the [TypeScript SDK](https://docs.commercetools.com/api/dev-tooling/ts-sdk-middleware.md#concurrent-modification-middleware) provide built-in handling for this scenario through the `ConcurrentModificationMiddleware`. It automatically retries requests that return a 409 status code using an exponential backoff strategy. ### 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](https://docs.commercetools.com/api/general-concepts.md#correlation-id) to trace request flow and isolate timeouts. - [Application performance monitoring](https://docs.commercetools.com/api/dev-tooling/observability.md) 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. 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](https://docs.commercetools.com/api/error-handling.md#recommended-timeout-values) based on use case and system architecture. - Use [exponential backoff delays](https://docs.commercetools.com/api/error-handling.md#exponential-backoff) before retrying the request. - Define a [maximum number of retry attempts](https://docs.commercetools.com/api/error-handling.md#maximum-retry-attempts). - Monitor and log all retry and timeout behavior for observability and tuning. - Adjust retry behavior based on observed performance in production. By adopting these practices, your application can better tolerate latency, maintain responsiveness, and handle failure better. ## Related pages - [Section overview page](https://docs.commercetools.com/api.md) - [Previous page: Large Carts](https://docs.commercetools.com/api/large-cart-performance-tips.md) - [Next page: Load testing](https://docs.commercetools.com/api/load-testing.md)