API Timeout Error in Node.js: Causes, Fixes, and Circuit Breaker Patterns

Node.js made a deliberate design decision not to impose a default timeout on HTTP connections. The rationale was that timeout values are application-specific: a health check endpoint should time out in 1 second, a file upload might need 5 minutes, and a streaming connection might legitimately never close. Baking in a global default would either be too short for legitimate long-running requests or too long to protect against hung connections. This philosophy puts the burden on developers to configure timeouts explicitly, which many omit entirely.

The result is that a Node.js server making outbound HTTP requests without explicit timeouts can accumulate thousands of pending connections to a slow or unresponsive upstream. Each pending request holds a socket, occupies a slot in the connection pool, and keeps its promise unresolved. The Event Loop continues processing other requests, but over time the backlog grows until the process runs out of file descriptors, memory, or connection pool capacity — and then all requests start failing, not just those going to the slow upstream.

The complexity is deepened by the fact that timeouts in HTTP have multiple phases. A TCP connection timeout fires if the three-way handshake never completes, which usually indicates a firewall dropping packets silently. A socket inactivity timeout fires when no data has been transferred for a given period after the connection is established. A total request timeout caps the entire operation from connection attempt to final byte received. Node.js exposes socket-level timeouts through socket.setTimeout() and req.setTimeout(), but these control inactivity, not total duration. AbortController with setTimeout is the standard way to set a total deadline.

Serverless environments add a third layer of timeout concerns. AWS Lambda has a per-function timeout configurable up to 15 minutes, but API Gateway — the most common way to expose Lambda functions as HTTP endpoints — enforces its own 29-second timeout regardless of the Lambda setting. A Lambda function can be configured for 10 minutes but will receive a 504 response from API Gateway after 29 seconds. Cloudflare Workers have a 10ms CPU time limit on the free plan and 50ms on paid plans — a CPU budget, not a wall-clock limit — so under concurrent request load, CPU time can be exhausted faster than expected.

The first diagnostic step is measuring how long each phase of the request takes. Add timestamps before the fetch call, after response headers arrive, and after the body is fully read. The gap between each timestamp identifies which phase is slow. If the connection takes 20 seconds and the body reads in 100ms, the problem is with the server starting to respond. If the connection is fast but the body read takes minutes, the issue is payload generation time on the server or a streaming response blocking the client.

In the browser, use DevTools Network tab to break down request timing. Select the failing request and look at the Timing panel: DNS lookup, TCP connect, TLS handshake, TTFB (time to first byte), and content download are shown separately. For API requests, TTFB is the most diagnostic number — a high TTFB means the server is slow to process the request, not that the network is slow. Use the /tools/http-request-builder on ToolDock to send the same request from a neutral location and compare timing values.

For Node.js server-side requests, add performance.now() measurements around each fetch call and log the duration with the request URL and response status. When logs show certain URLs consistently taking over 2 seconds, those are the candidates causing timeout-induced problems under concurrent load. Correlate slow request logs with server memory usage and connection pool size metrics — high memory usage often indicates connection pool exhaustion from accumulated hung requests.

For AWS Lambda, check CloudWatch Logs for the invocation that timed out. Lambda logs the duration and whether the function hit its configured timeout. If the logged duration is exactly 29000ms and the Lambda timeout is set higher, API Gateway is enforcing its own limit. If the duration matches the Lambda configured timeout exactly, the function itself ran out of time. Look for the last log lines before the timeout to see what the function was executing when the clock ran out.

For distributed tracing of downstream dependency timeouts, use X-Ray or an OpenTelemetry SDK to add spans around each outbound HTTP call. Spans capture exact timing per downstream request and make it immediately obvious which dependency is slow when multiple external API calls run in parallel. The /tools/cors-tester and /tools/http-request-builder tools on ToolDock let you check if a specific API endpoint is currently responding within acceptable time, independently of your application code.

For native Node.js fetch (Node.js 18+) or undici, use AbortController with a cleared timer in a finally block. This pattern is the most composable because the controller can also be triggered by user cancellation, component unmount in React, or a parent timeout higher in the call stack. Pass the signal into every fetch call that should respect the timeout. When using undici directly, prefer its headersTimeout and bodyTimeout options over a single AbortController for fine-grained phase control.

For Axios in Node.js, the timeout option sets an inactivity timeout via socket.setTimeout(), not a total request duration. A request that trickles data slowly can reset the inactivity timer indefinitely and never trigger the Axios timeout. For strict total-duration enforcement with Axios, combine an AbortController signal with the Axios timeout option. Both mechanisms run in parallel and the one that fires first cancels the request.

For AWS Lambda with API Gateway, design handlers to complete within 25 seconds to leave a 4-second buffer before the 29-second hard limit. Use Promise.race() to compete a real response against a timeout that returns a meaningful error payload — the function returns before API Gateway terminates it, so the client receives a structured error instead of a 504 with an empty body. Set individual downstream API timeouts to 10-15 seconds to leave room for at least one retry cycle.

For database query timeouts, set them at the database client level separately from HTTP timeouts. Prisma supports query timeouts via the queryTimeout option. The pg package supports query_timeout in the pool configuration. These database timeouts must be shorter than the HTTP response timeout — if the HTTP timeout is 10 seconds and the database timeout is also 10 seconds, there is no time left to construct a proper error response. A rule of thumb: database timeout should be 70-80% of the HTTP timeout budget.

For services that experience repeated timeouts from a specific upstream, implement a circuit breaker using the opossum npm package. After a configurable number of consecutive failures, the circuit opens and immediately rejects requests to that dependency for a cooldown period. This prevents timeout accumulation where one slow dependency degrades the entire application by filling the Event Loop with hanging promises.

Cloudflare Workers measure CPU time rather than wall-clock time. A Worker that makes five sequential outbound fetch calls might take 500ms of wall-clock time but only 2ms of CPU time — the CPU budget is consumed only by JavaScript execution, not by waiting for I/O responses. Workers can call slow APIs without hitting the CPU limit, but computation-heavy Workers can hit the limit even on fast networks. Do not use CPU time limits as a mental model for timeout behavior on I/O-heavy workloads.

Vercel serverless functions have a default timeout of 10 seconds on the Hobby plan and 60 seconds on the Pro plan. The timeout applies to total execution time. If your function makes two sequential 6-second API calls, it will timeout on the second call even though each individual call is individually reasonable. Use Promise.all() for independent parallel calls to reduce total wall-clock time and fit within the platform timeout.

Keep-alive connections pool TCP connections for reuse across requests. When a pooled connection is idle and the server closes it, Node.js does not immediately detect the closure — it only discovers the dead connection when it tries to use that socket for the next request. This appears as an ECONNRESET error that superficially resembles a timeout but is actually a stale connection. Setting keepAlive on the http.Agent and configuring a low idleTimeout flushes dead connections before they produce unexpected errors.

The Retry-After response header, returned by APIs on 429 or 503 responses, specifies how long to wait before retrying. It can be a number of seconds or an HTTP date string. Parsing it correctly requires handling both formats: use parseInt() for numeric values and Date.parse() for date strings, then compare against Date.now(). When an API sends Retry-After, respect the value rather than immediately retrying — ignoring it can cause the server to extend its backoff window and ban the client IP.

Node.js 18+ global fetch with a URL that follows a redirect does not always inherit the AbortController signal timeout across the redirect boundary consistently across minor versions. If a redirected URL is slow and the original timeout fires between the initial request and the final response, the AbortError is thrown. Test this behavior explicitly in your Node.js version because the fetch spec behavior for signal inheritance through redirects changed across minor versions.

Calling req.setTimeout() and assuming the socket closes is the most common Node.js timeout bug. The timeout event is purely informational — Node.js does not automatically destroy the socket when it fires. Developers add req.setTimeout(5000, callback) and assume the request will be cancelled after 5 seconds, but without calling req.destroy() inside the callback, the request continues indefinitely. This bug is particularly subtle because in testing with fast local servers, the timeout never fires and the missing destroy() call is never exercised.

Cleaning up AbortController timers only in the catch block rather than in a finally block means successful requests leave behind active timers. The timer fires after the request completes and calls controller.abort() on a controller whose signal is attached to nothing — unless the same controller instance is reused for a subsequent request, in which case it aborts that request instead. Always use try/finally to guarantee clearTimeout runs regardless of whether the request succeeded, failed, or was cancelled.

Setting the same timeout value for all operations in an application leads to either overly strict timeouts on legitimately slow operations or overly lenient timeouts on simple reads. Profile actual API endpoint response times and set timeouts that reflect the 99th percentile response time plus a reasonable buffer. A 5-second timeout is appropriate for a user profile fetch; a 30-second timeout is appropriate for a report generation endpoint that runs complex aggregation queries.

Not accounting for connection pool wait time is a subtle source of apparent timeouts that are actually client-side queuing. If your http.Agent has maxSockets set to 5 and six requests arrive simultaneously, the sixth request waits in a queue until a socket frees up. This queue wait counts against the request's total time but has nothing to do with network or server speed. Increase maxSockets or use undici's connection pooling configuration with higher concurrency limits to reduce queuing delays under load.

Forgetttng that AbortController signals are one-use is a common source of confusing immediate request failures. Once a signal is aborted, it stays aborted permanently. If you create one controller, use it for a request, that request completes or times out, and then you pass the same signal to a new request — the new request starts in an already-aborted state and fails immediately. Always create a fresh AbortController for each new request.

Define timeout budgets at the service boundary and cascade them downward. If an incoming HTTP request has a 10-second budget, allocate specific portions: 6 seconds for the primary database query, 2 seconds for a cache lookup, 1 second for any external enrichment API call, and 1 second for response serialization. Each downstream call gets an AbortController signal derived from the remaining budget, not a static value. This prevents the sum of individual timeouts from exceeding the total service boundary timeout that the calling client is waiting for.

Implement a circuit breaker for every external dependency. The circuit breaker tracks failure rate over a rolling window. When the failure rate exceeds a threshold — say, 50% over the last 30 seconds — the circuit opens and all new requests to that dependency fail immediately with a clear error rather than accumulating as hanging promises. The circuit closes again automatically after a cooldown period and lets through a test request to see if the dependency recovered. Use opossum for a production-tested Node.js circuit breaker implementation.

Log every request timeout with enough context for diagnosis: the URL, the timeout duration, how long the request had already been running when cancelled, current server memory usage, and the count of in-flight requests to that host. When reviewing production logs, patterns in this data reveal whether a timeout is caused by a slow dependency, connection pool exhaustion, or server-side load shedding. Without this context, timeout logs are indistinguishable noise from one another.

Use the /tools/http-request-builder on ToolDock to establish a baseline for how long specific API endpoints take to respond under normal conditions. Save the measurements and compare them over time — if an endpoint that used to respond in 300ms now takes 800ms consistently, that signals a need to investigate the upstream API before it starts causing timeout failures at scale.

For Node.js applications deployed behind API Gateway or a load balancer, set your application-level timeout 10-20% shorter than the infrastructure timeout. This ensures your application returns a properly formatted error response before the infrastructure terminates the connection, giving clients a meaningful error body instead of an abruptly cut TCP stream. The infrastructure timeout should act as an emergency safety net, not the primary timeout mechanism your application relies on.