Fix HTTP 504 Gateway Timeout API Errors

HTTP 504 means a gateway exceeded its deadline while waiting for an upstream response. Trace where time was spent before increasing limits or adding retries.

Map the request path and deadlines

List every hop from client through CDN, load balancer, ingress, application, database, and downstream API. Record the timeout configured at each layer. An outer deadline should allow an inner operation to stop, return an error, and clean up before the gateway abandons the connection. Conflicting defaults can cause a proxy to return 504 while the application continues expensive work.

Measure the slow phase

Use a correlation ID and distributed timing data to separate DNS, connection, TLS, queueing, application processing, database queries, downstream calls, and response transfer. Compare normal and failing percentiles rather than one average. Check whether failures cluster around a specific duration, endpoint, tenant, payload size, region, or deployment. A sharp cutoff commonly reveals the enforcing timeout.

Reduce upstream work

Look for slow queries, missing indexes, lock contention, exhausted connection pools, repeated remote calls, oversized responses, and synchronous jobs. Bound result sets and paginate. Cache stable data where correctness permits. Move work that cannot reliably finish within the request budget to a queue and return an operation identifier so the client can check status later.

Propagate cancellation and budgets

When the client disconnects or a deadline expires, cancel downstream requests and database work where supported. Pass a smaller remaining budget to each dependency instead of allowing every call its full default timeout. Reserve time for serialization and the response path. This prevents abandoned requests from consuming capacity and causing more timeouts.

Retry only when safe

A 504 does not prove that no state changed. The upstream may finish after the gateway stops waiting. Retry reads with a small bounded budget, exponential backoff, and jitter. For writes, use an idempotency key or query operation status before repeating. Apply a total deadline so nested retries cannot multiply one user request into minutes of work.

Avoid timeout inflation as the first fix

Increasing one gateway timeout can hide a regression, tie up connections, and shift failure to the next layer. Extend a deadline only when the operation is intentionally long, resource use is bounded, clients can wait, and every surrounding limit is aligned. Prefer an asynchronous workflow for exports, large imports, and other naturally long tasks.

Verify under realistic load

Test latency, cancellation, retries, and duplicate prevention under expected concurrency. Confirm the public path no longer returns 504 and that upstream work stops after canceled requests. Inspect response timing and gateway fields with the HTTP Header Analyzer.

Frequently Asked Questions

Related Tools and Guides