---
title: "HTTP 504 Gateway Timeout: what it means and how to fix it"
url: https://proxy.wiki/glossary/http-status-504/
type: Glossary Term
author: "proxy.wiki editorial"
published: 2026-10-21
updated: 2026-10-21
site: proxy.wiki
topics: ["Proxy fundamentals"]
license: CC BY 4.0; quote freely with attribution to https://proxy.wiki/
---

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

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

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](https://www.rfc-editor.org/rfc/rfc9110#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](/glossary/via-header/) 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](/guides/502-vs-504/) explains the status boundary, and [curl proxy diagnostics](/guides/how-to-use-a-proxy-with-curl/) 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](https://www.rfc-editor.org/rfc/rfc9110#section-15.6.5)
2. [IANA HTTP Status Code Registry](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml)
