Troubleshooting
How does a 504 differ from a 502 response?
Short answer
A 502 means a gateway received an invalid response from an upstream server. A 504 means the gateway did not receive a response in time. Both point to the link between proxy and upstream, but the likely checks differ.
What changes the answer
- Invalid response versus timeout
- Which proxy produced the status
- Upstream process health and timeout settings
What the specifications say
RFC 9110 defines 502 Bad Gateway as the server, while acting as a gateway or proxy, receiving an invalid response from an inbound server it accessed while attempting to fulfil the request. It defines 504 Gateway Timeout as the server, while acting as a gateway or proxy, not receiving a timely response from an upstream server it needed to access.
In plain terms
With a 502, the proxy reached something, or tried to, and what came back was not usable. With a 504, the proxy waited and nothing came back before its time limit. Applications and intermediaries differ in how exactly they use the codes, so confirm with the logs rather than assuming.
Checks for a 502
- Is the upstream process running and listening on the address or socket the proxy uses?
- Did a deployment change the port, socket or address?
- Did the process crash or restart during the request?
- Do the proxy's error log and the application's log show matching entries?
Checks for a 504
- Which request was slow, and what was it waiting for: a database, an external API, a lock?
- Is the proxy's timeout shorter than the work takes? Nginx has separate settings for connecting, sending and reading, documented in its proxy module reference.
- Did load increase so requests queued behind busy workers?
Avoid blind fixes
Raising a timeout can hide a slow query, and restarting every service can interrupt unrelated sites on a shared server. Identify which component generated the response, correlate timestamps in the logs, change one thing, and repeat the original request. The troubleshooting checklist helps you note the status code, time and path before you start.
An example
A checkout request calls a payment API that stalls. The proxy waits, reaches its read timeout and returns a 504, while the application log shows a long-running request. Raising the proxy timeout would only make users wait longer; the useful step is to investigate the stalled external call. If instead the application process had crashed, the proxy would typically fail to get a valid response, and a 502 is the more likely result.