502 Bad Gateway
A server acting as a gateway or proxy received an invalid response from the upstream server it contacted.
Status
HTTP/1.1 502 Bad Gateway
Details
- Category: 5xx
- Status: Standard. Registered with IANA and defined by a current standards-track RFC.
- Specification: RFC 9110 §15.6.3
- Cacheable: Only with explicit cache headers
- Response body: Allowed
- Retry: Safe to retry
502 is reported by the intermediary, not by the origin. The reverse proxy, load balancer, or CDN reached upstream and got something it could not use: a connection refused, a connection reset mid-response, a malformed status line, or nothing at all.
The distinction from 504 is precise and useful. 504 means the upstream was too slow, 502 means the upstream answered badly or not at all. If a service crashes on start, everything in front of it reports 502 until it comes back.
Common causes
- The upstream application is not running, or crashed while handling the request.
- The proxy is pointed at the wrong port or an unreachable host.
- The upstream returned a malformed response, or closed the connection before finishing.
- A container was replaced during a deploy and the proxy still holds the old address.
- A TLS failure between the proxy and the upstream, such as an expired origin certificate.
How to fix it
As the client
- Retry with backoff. Deploy-related 502s clear on their own within seconds.
- Confirm the failure is not local by testing another endpoint on the same host.
As the server
- Check whether the upstream process is running and listening on the expected address and port.
- Read the proxy error log. nginx names the upstream and the exact failure, which the client's 502 page never will.
- Match keepalive and timeout settings between the proxy and the application so the proxy does not reuse a socket the app has closed.
- Use health checks and connection draining so deploys do not send traffic to instances that are not ready.
Examples
GET /api/v2/order HTTP/1.1 Host: api.example.com HTTP/1.1 502 Bad Gateway Content-Type: text/html; charset=utf-8 Server: nginx
Notes for proxy users
Through a forward proxy, a 502 can come from the proxy itself when it cannot reach the destination host, or from a reverse proxy at the destination. Requesting a known-good site through the same proxy separates the two in one step: if that succeeds, the proxy is healthy and the target's infrastructure is the problem.