Skip to content
5045xx · Server errorThe server has erred, or cannot perform the request. RFC 9110 §15.6

HTTP 504 Gateway Timeout: what it means and how to fix it

Meaning

HTTP 504 Gateway Timeout means a gateway did not receive an upstream response before its deadline. Locate the timer before changing proxy exits.

Covered in a guide502 vs 504 at a glanceA section of 502 vs 504: Bad Gateway vs Gateway Timeout

HTTP 504 means a gateway or proxy did not receive a timely response from the upstream server: “Gateway Timeout”. RFC 9110 section 15.6.5 defines the code and says the client may retry the request. The gateway can be healthy while the upstream is slow, unreachable or waiting on another dependency. A client-side timeout before any response is not a 504.

One request can cross several timers. The browser may give up first, a forward proxy may wait longer, and a reverse proxy may have a third deadline. The status only identifies the layer that wrote it. Capture elapsed time, Server, Via and both CONNECT and inner status values when a proxy is involved.

Reproduce a gateway deadline

The local Python 3.15.0 rig has an upstream that sleeps for ten seconds and a gateway that waits three seconds. It returns 504 while the client is still connected:

from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from urllib.request import urlopen
from urllib.error import URLError
import time

class Gateway(BaseHTTPRequestHandler):
    def do_GET(self):
        try:
            urlopen("http://127.0.0.1:8544/slow", timeout=3)
            code, body = 200, b"ok\n"
        except (URLError, TimeoutError):
            code, body = 504, b"Upstream did not answer within 3 s.\n"
        self.send_response(code)
        self.send_header("Content-Type", "text/plain")
        self.send_header("Content-Length", str(len(body)))
        self.end_headers()
        self.wfile.write(body)

ThreadingHTTPServer(("127.0.0.1", 8541), Gateway).serve_forever()
$ curl -sS -i -w "elapsed=%{time_total}s\n" "http://127.0.0.1:8541/slow?s=10"
HTTP/1.0 504 Gateway Timeout
Server: BaseHTTP Python/3.15.0
Content-Type: text/plain
Content-Length: 36

Upstream did not answer within 3 s.
elapsed=3.002233s

The capture used curl 8.7.1. With -m 2, curl itself stopped at about two seconds and printed curl: (28) Operation timed out; no 504 existed because the client closed before the gateway’s three-second response. A requests 2.32.3 retry test waited for the gateway’s 504 and exhausted its retry budget after 11.0 seconds. The timeout that wins determines what the caller sees.

504 through a forward proxy

Squid can return 504 when an HTTP origin does not answer, or after a CONNECT tunnel when the upstream TLS connection stalls. A reverse proxy such as nginx can return 504 while waiting for an application server. The body and response headers identify the writer. If the gateway relays a 504 from farther upstream, preserve the original request ID and inspect every Via hop.

Do not “fix” a 504 by increasing every timeout. A longer deadline can tie up a worker and make overload worse. Start by measuring the upstream phase: DNS, connect, TLS, request write or response read. If the upstream eventually returns a response, the gateway timeout is a capacity or deadline mismatch. If it never connects, investigate routing and firewall rules.

Retrying a timed-out write can duplicate work if the server processed it just before the gateway gave up. Use an idempotency key or a status lookup when the API supports one, and cap retries.

Causes and fixes

Cause Evidence What to change
Upstream application exceeds gateway deadline 504 arrives at a stable boundary and upstream logs show longer work Reduce work, stream progress or align the deadline with a measured operation
DNS or connect failure at the gateway Gateway logs show name resolution or connect errors, and no upstream request ID Fix resolver, route or firewall configuration
TLS handshake stalls inside CONNECT CONNECT succeeds but TLS never completes; client reports a later timeout Check the upstream certificate, interception policy and handshake timeout
Forward proxy cannot reach the origin Proxy signs the 504 and includes a vendor diagnostic Check proxy egress and target reachability before changing the scraper
Client timeout is shorter than gateway timeout curl error 28 or a library timeout, with no HTTP status Set a client deadline longer than the intended gateway deadline, or handle the transport timeout explicitly
Retry storm Each retry adds load and the next response arrives later Use bounded retries, backoff and a shared queue per host

A scraper should keep 504 separate from 502 and from a local timeout. The 502 vs 504 comparison explains the status boundary, and curl proxy diagnostics shows how to record CONNECT timing. If the same URL succeeds direct but times out through one exit, investigate that route. If all exits time out together, measure the origin first.

Frequently asked questions

Should I retry a 504?
Only with a bounded policy and a safe or idempotent operation. A timeout does not prove that the server did nothing.
What is 504 versus 408?
408 means the server stopped waiting for your request to arrive. 504 means a gateway stopped waiting for its upstream response.

Sources

  1. RFC 9110 section 15.6.5: 504 Gateway Timeout
  2. IANA HTTP Status Code Registry

Also covered in

All terms, A to Z