Quick answer: A 502 Bad Gateway means the gateway or proxy reached the upstream but got a response it could not accept, such as a malformed reply or a dropped connection. A 504 Gateway Timeout means it waited for the upstream and never received a response in time. The first is a broken response; the second is a missing response.

What each status code means

Both codes are produced by an intermediary: a reverse proxy, load balancer, or CDN in front of your application. They are not 4xx client errors, and the upstream usually did not emit that status. The distinction is what the intermediary observed when it called the upstream.

Signal 502 Bad Gateway 504 Gateway Timeout
Upstream contact Reached the upstream Reached or connected, then waited
What came back An invalid or unusable response No response before the deadline
Typical layer Upstream process, protocol, or DNS Upstream speed, capacity, or timeout config
First place to check Upstream process and its logs Upstream latency and gateway timeout

Why a 502 happens

The gateway opened a connection and the upstream failed to deliver a valid response, often because the application process crashed or restarted mid-request, so the socket closes or resets.

Configuration mismatches produce the same result. If the proxy speaks HTTPS to an upstream that only listens on HTTP, or points at a port with no healthy service, the returned bytes are not a valid response. Stale DNS can send the proxy to a dead host, and malformed headers or an upstream that closes before sending headers also land here.

Why a 504 happens

The gateway connected, forwarded the request, and waited past its timeout without a complete response. The upstream is alive but too slow or stalled. A slow query, a long-running job, or a call to another slow dependency can push the handler beyond the proxy's read timeout.

Resource exhaustion looks the same: when the worker or connection pool is full, requests queue until the proxy gives up, and a deadlock or blocked call can stall a worker. The gateway cannot tell slow from hung, so it returns 504 at its deadline.

How to isolate the failing layer

Bypass the gateway and send the same request directly to the upstream port. A reset or malformed output puts the fault in the application; a slow but successful call points to the proxy timeout and a latency problem.

Read the gateway error log alongside the application log. A reverse proxy records the upstream address and the exact failure, such as a reset, empty reply, or read timeout, which removes the guesswork. Confirm the process is running, then check protocol, port, and DNS. For a 504, measure the handler's real duration and compare it with the timeout before changing anything.

Fixing each failure

For a 502, repair the upstream so it returns a valid response: stabilize the crashing process, correct the protocol and port, and fix stale DNS. A restart may clear a wedged process, but a recurring reset points to a code or resource fault it will not fix.

For a 504, address the slow path. Optimize the query or handler, add capacity so the pool is not saturated, or move long work onto an async job and return quickly. Raising the timeout is valid only when the operation is genuinely slow and the client can wait; if the handler is stuck, a larger timeout hides the defect.

Verifying client behavior offline

You can confirm client handling without the live gateway. A local mock can return 502 in one case and 504 in another while recording requests, and a scenario can assert status and headers at each step as evidence. Powerduck sends these requests through the local main process without browser CORS limits, runs the assertions, and records mock traffic. For more, see the API debugging guide hub.

Honest limits

A status code narrows the failure but does not prove the root cause. A 502 can come from a crash, a bad port, or DNS, and a 504 can reflect a slow query or a full pool, so the logs stay the source of truth. A local mock reproduces the status to test client logic; it cannot reproduce a real upstream crash or a production network stall.

Frequently asked questions

Is a 502 or 504 the client's fault? No. Both are reported by the gateway about the upstream. Retrying a 502 from a crash only helps once the service is back.

Should I retry on a 504? A single retry can clear a transient stall, but repeated retries add load to a saturated upstream. Bound the retry and do not retry a non-idempotent write.

Does increasing the timeout fix a 504? Only when the request is genuinely slow and expected to finish. If the upstream is hung, the timeout masks the problem.

The bottom line

Read the code as a direction: 502 means the upstream answered badly, so inspect the process, protocol, and DNS; 504 means it did not answer in time, so inspect latency, capacity, and the timeout. Confirm with a direct request and both logs, fix the real fault rather than only widening the timeout, and verify the client against a mock returning each status.