What this usually means
A timeout means the client stopped waiting for a response. It does not mean the operation failed. Load balancers, API gateways, and HTTP clients all have timeout settings. If any timeout in the chain is shorter than the processing time, the connection is terminated while the server continues processing. This creates a gap where the client retries but the original request succeeds, creating a duplicate.
The first ten minutes \u2014 establish facts before touching code.
- 1Identify which timeout is firing: client, load balancer (504), API gateway, or server?
- 2Log the start and end time of the server-side handler. How long does it actually take?
- 3Check if the timeout is consistent or intermittent. Intermittent suggests resource contention.
- 4Check if the server continues processing after the client times out by inspecting server logs.
- 5Check for a slow downstream dependency like a database query or external API call.
The specific files, logs, configs, and dashboards that usually own this bug.
- searchClient timeout configuration in axios, fetch with AbortController
- searchLoad balancer timeout settings — AWS ALB idle timeout (default 60s), Nginx proxy_read_timeout
- searchAPI gateway timeout — usually 29 to 30 seconds for many platforms
- searchServer timeout — Express server.timeout, Node.js server.setTimeout()
- searchServer-side handler timing logs
- searchDownstream dependency health — database query times, external API response times
Practical causes, not theory. These are the things you will actually find.
- warningLoad balancer or API gateway has a 30-second timeout but the endpoint takes 45 seconds
- warningDatabase query is slow with no index or inefficient query plan
- warningExternal API call blocks the request — the third-party service is slow or unreachable
- warningServer is overloaded — requests queue up waiting for a free thread or connection
- warningClient timeout is set too low for inherently long-running operations
- warningLong-running synchronous processing should be moved to a background job
Concrete fix directions. Pick the one that matches your root cause.
- buildMove long-running work to a background job: accept the request, return 202 Accepted with a status URL
- buildIncrease the specific timeout that is too short after verifying the operation time is acceptable
- buildCancel server-side processing if the client disconnects by listening to the close event
- buildOptimise the slow operation: add database indexes, cache results, parallelise independent work
- buildUse a request queue with callback or webhook instead of synchronous request-response
A fix you cannot prove is a guess. Close the loop.
- verifiedTest with a request that takes longer than each timeout threshold.
- verifiedAfter moving work to background jobs, verify the initial request returns quickly.
- verifiedMonitor timeout rates in production — they should trend to zero after fixes.
- verifiedTest retry behaviour: a retry after timeout should not create a duplicate operation.
- verifiedLoad test the endpoint to confirm it handles concurrent requests without timeout spikes.
Things that make this bug worse or harder to find.
- warningArbitrarily increasing timeouts without understanding why the operation is slow
- warningNot handling the case where the server succeeds after the client times out
- warningSetting client timeouts shorter than load balancer timeouts
- warningNot implementing idempotency for operations that are retried after timeouts
- warningAssuming a timeout always means failure