Skip to content
Fix These Errors
HTTP 504 Gateway Timeout — What It Means & How to Debug

HTTP 504 Gateway Timeout — What It Means & How to Debug

DodaTech Updated Jun 20, 2026 4 min read

HTTP 504 Gateway Timeout is an HTTP response status code that indicates a server acting as a gateway or proxy did not receive a timely response from an upstream server. The proxy was willing to wait only so long for the backend to respond, and the backend exceeded that limit.

What It Means

Defined in RFC 7231 Section 6.6.5, the 504 status code sits between 502 (bad response) and 503 (server overloaded) in the 5xx family. The gateway successfully connected to the upstream server and forwarded the request, but the upstream either never responded or took longer than the configured timeout.

Unlike a 502 (where the upstream returns garbage), a 504 means the upstream returned nothing at all within the expected time frame.

When It’s Sent

  • Slow database queries — A complex SQL query takes 30 seconds, but the proxy timeout is 10 seconds.
  • Upstream server overloaded — The backend is so busy that requests sit in its queue past the proxy timeout.
  • External API timeout — Your application calls a third-party API that is slow or unresponsive, and the gateway times out waiting for your app server.
  • Proxy timeout too low — The default proxy timeout (e.g., Nginx proxy_read_timeout 60s) is not high enough for long-running requests.
  • Backend process deadlock — The application server is alive but stuck (e.g., a mutex deadlock), so it never sends a response.

Real Example

The following curl command hits an endpoint that deliberately sleeps before responding:

curl -v https://httpbin.org/delay/15

Expected response (depending on proxy timeout configuration):

< HTTP/1.1 504 GATEWAY TIMEOUT
< Date: Sat, 20 Jun 2026 12:00:00 GMT
< Content-Type: text/html; charset=utf-8
< Content-Length: 184
<
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<title>504 Gateway Timeout</title>
<h1>Gateway Timeout</h1>
<p>The server did not receive a timely response from an upstream server.</p>

A typical Nginx 504 page:

<html>
<head><title>504 Gateway Time-out</title></head>
<body>
<center><h1>504 Gateway Time-out</h1></center>
<hr><center>nginx/1.24.0</center>
</body>
</html>

How to Debug

Client-Side

  1. Retry with backoff — A 504 may be transient. Wait a few seconds and try again.
  2. Check the server status page — Large services often report degraded performance on their status dashboard.
  3. Simplify the request — If you sent a complex query or large payload, try a simpler request to see if the backend responds faster.
  4. Contact the administrator — If the error persists, report the URL and timestamp. Include the X-Request-Id header if present.

Server-Side

  1. Increase proxy timeout — Adjust proxy_read_timeout (Nginx), ProxyTimeout (Apache), or Timeout (HAProxy) to match the expected response time of the slowest legitimate request.
  2. Profile the upstream — Use application profiling tools (XHProf, Datadog APM, Jaeger) to identify why the backend is slow. Common culprits: N+1 queries, missing indexes, or external API calls.
  3. Implement streaming — If the backend generates a large response, stream it incrementally so the proxy sees data flowing before the timeout.
  4. Add health checks — Configure the proxy to detect and remove unresponsive upstreams from the pool.
  5. Use async processing — For long-running operations, accept the request immediately with a 202 Accepted and provide a status URL for polling.
  6. Review upstream logs — The backend may show slow query logs, error traces, or deadlock warnings.

Common Causes Table

ScenarioLikely CauseHow to Fix
Complex analytics queryQuery runs for minutes, proxy times out in 30sIncrease timeout for that route; optimize query; use materialized views
Third-party API slowUpstream app calls external API with no timeoutSet a shorter timeout on external calls; use circuit breaker
Backend under heavy loadRequest queue builds up past proxy timeoutScale up; add connection pooling; rate-limit at proxy
Nginx default timeoutproxy_read_timeout set to 60s, request takes 90sIncrease timeout or optimize backend response time
Deadlocked databaseTransaction A holds lock, Transaction B waits foreverKill blocking transactions; fix locking order in code

FAQ

What is the difference between 504 and 502?
A 502 (Bad Gateway) means the upstream returned an invalid response. A 504 (Gateway Timeout) means the upstream did not return any response within the timeout period.
Can I fix a 504 by increasing my server timeout?
That is one approach, but it is often a band-aid. A better fix is to identify why the upstream is slow and address the root cause — optimize the query, add caching, or use async processing. If the slow path is expected, then raising the timeout is appropriate.
Is a 504 the same as a connection timeout?
No. A connection timeout happens when the TCP handshake itself fails. A 504 happens after the connection was established and the request was forwarded — the proxy was waiting for the response bytes.

Related Codes

HTTP 502 Bad Gateway — An upstream server returned an invalid response.

HTTP 503 Service Unavailable — The server is temporarily unable to handle the request.

HTTP 500 Internal Server Error — A generic server-side error.

HTTP 408 Request Timeout — The server timed out waiting for the client’s request.

Previous HTTP 503 Service Unavailable — What It Means & How to Debug Next HTTP 100 Continue — What It Means & How to Use

Built by the developers of DodaTech

Doda Browser, DodaZIP & Durga Antivirus Pro

Home Browse Fix These Errors