Performance & Debugging

Handle API Timeouts and Retries Without Amplifying Outages

Set deadlines and retry policies for outbound calls that improve resilience without creating retry storms or duplicate operations.

A timeout is a limit on how long your application is willing to wait; it is not proof that the remote operation did not happen. The provider may have completed a request while the response was lost. Retrying a payment or order creation without an idempotency strategy can therefore create duplicate effects.

Use a total deadline

Set connection and response timeouts, but also enforce an overall deadline for the whole workflow. A chain of five services each allowed to wait 30 seconds can exceed the user's request budget. Pass remaining time through internal calls and stop starting new work when the deadline is exhausted.

Retry only transient failures

Network interruptions, selected 5xx responses and 429 responses may be retryable according to provider documentation. Validation errors and most authentication failures are not. Use exponential backoff with random jitter and a small maximum attempt count. Honor Retry-After when present. Avoid synchronized fixed-interval retries that cause every client to hit the provider at the same moment.

Protect non-idempotent operations

Use a provider-supported idempotency key for create or charge operations. Reuse the same key for retries of the same logical action; do not generate a new key for each attempt. If the provider does not support idempotency, reconcile the operation's state before retrying when possible.

Fail visibly and recover deliberately

Distinguish timeout, DNS/TLS failure, HTTP rejection and invalid response. Record safe correlation identifiers and timing data. A circuit breaker may temporarily stop calls to a failing dependency, but it needs clear thresholds, a half-open recovery state and metrics. It is not a replacement for timeouts.

Further reading

Share this page Help other developers discover this resource.