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

• A slow page or API call. A heavy database query, a report or an export takes longer than the gateway's timeout.
• A timeout too short on the reverse proxy or load balancer for what the app does. nginx, for example, waits 60 seconds for the upstream by default (proxy_read_timeout).
• An overloaded origin that accepts connections but answers slowly.
• Network trouble between the gateway and the origin: packet loss, a firewall silently dropping connections, or DNS pointing at an address that doesn't answer.
• On the proxy path: a slow exit connection, or a site that is slow to answer that exit.

As with a 502, check when the 504 arrived. In reply to CONNECT, before the tunnel opened, it came from your proxy, which couldn't connect to the site in time. Inside the tunnel, as a normal response, it came from the site's side.

Also check that you got a 504 at all. If your own client gives up first, you get a timeout error from your HTTP library (in Python requests, a Timeout exception), not a 504. That one you control with your client's timeout setting; a 504 comes from a gateway's timeout, which only whoever runs that gateway can change.

Then time the same request without the proxy. If the site is slow directly too, the delay is on the site's side.

As a visitor or client

1. Retry after a pause, with backoff. Timeouts often come from short spikes.
2. Make sure your client's own timeout is longer than the site normally needs, so you see the server's real answer.
3. Ask for less per request where the API allows it: smaller pages of results, narrower date ranges.
4. If the 504 came from the proxy, test the line against a simple endpoint and check that the product has bandwidth left. On a rotating line, a retry leaves from a different exit.

As the site owner

1. Find the slow step in the logs: which endpoint, which query.
2. Move long work to background jobs and return early, instead of raising timeouts everywhere.
3. If a long timeout is genuinely needed, raise it on every layer in the chain (CDN, load balancer, reverse proxy): the shortest one wins.
4. On Cloudflare, a timeout waiting for the origin shows as Cloudflare's own error 524 rather than a 504.

# --connect-timeout limits connection setup; --max-time limits the whole transfer.
# A 504 is a gateway's verdict; curl exit code 28 means your own limit ran out first.
curl --connect-timeout 10 --max-time 90 --retry 3 -x "http://USERNAME:PASSWORD@HOST:PORT" https://example.com/report

import requests

proxy = "http://USERNAME:PASSWORD@HOST:PORT"
try:
    # (connect timeout, read timeout) in seconds
    r = requests.get("https://example.com/report", proxies={"http": proxy, "https": proxy}, timeout=(10, 90))
    if r.status_code == 504:
        print("A gateway on the site's side timed out:", r.headers.get("Server"))
except requests.exceptions.ProxyError as err:
    print("The proxy failed the CONNECT request:", err)
except requests.exceptions.Timeout:
    print("Our own client gave up first: no 504 was received")

For automatic retries that honour Retry-After, use the backoff function in the 429 guide; it retries 504s too.

Residential and mobile exits are consumer connections, so some are slower than others. On a rotating line, a retry leaves from a different exit.

On a sticky session, a slow exit stays your exit for as long as the session keeps its IP. If a sticky session keeps timing out, generate a new line to start a new session. On Core Residential, sticky is on or off and usually keeps the same IP for around 10 minutes; on Premium Residential you set the length, from 3 minutes to 24 hours.

Don't answer timeouts by opening many more parallel connections to the same site. If the site is slow because it is busy, that makes it slower. Back off instead.

If timeouts show up on one site and not on others through the same line, the site is the slow part.