502 Bad Gateway
This is an educational reference page about HTTP 502 Bad Gateway. The page itself is served as 200 OK so it can be indexed as HTTP documentation.
The server, while acting as a gateway or proxy, received an invalid response from an inbound server it accessed while trying to fulfill the request.
Specification
Registered in the IANA HTTP Status Code Registry as Bad Gateway. Defined in RFC 9110, Section 15.6.3.
What it means
HTTP 502 Bad Gateway means a gateway or proxy, such as nginx, a load balancer, or a CDN, got an invalid response from the server behind it. The proxy is working, but the connection or the answer from the upstream server failed. To fix a 502, start with the upstream server, not the proxy that reported it.
When to use it
- A proxy or gateway returns 502 when the upstream server closes the connection, resets it, or sends a response the proxy cannot parse.
- Use 504 instead when the upstream server did not answer in time.
- Application code behind a proxy rarely sends 502 itself. An API gateway can send it when a backend returns garbage.
Common causes
- The application process crashed or restarted, so the proxy's connection was refused or reset.
- The proxy points to the wrong port, socket, or host.
- The upstream server sent an invalid response, such as response headers larger than the proxy's buffer.
- TLS problems between the proxy and the upstream server, such as an expired or mismatched certificate.
How to fix it
- Check that the upstream process is running and listening on the address the proxy uses.
- Read the proxy's error log. nginx logs lines such as "connect() failed (111: Connection refused) while connecting to upstream".
- Check application logs and memory use for crashes and restarts around the same time.
- Raise the proxy buffer size if upstream response headers are large.
Examples
nginx in front of a crashed app
GET /dashboard HTTP/1.1
Host: app.example.com
HTTP/1.1 502 Bad Gateway
Server: nginx
Content-Type: text/html
<html><head><title>502 Bad Gateway</title></head>...Common mistakes
- Debugging the proxy config first when the upstream app is down. The 502 is usually a symptom.
- Returning 502 from application code for a failed call to a third-party API without saying which dependency failed.
- Retrying non-idempotent requests after a 502. The upstream may have processed the request before the connection broke.
Developer notes
502, 503, and 504 often come from infrastructure, not your code. Check the Server header and the error page format to see which layer sent the response: CDN, load balancer, or reverse proxy.
Questions
What does HTTP 502 Bad Gateway mean?
HTTP 502 means a proxy or gateway got an invalid response from the upstream server it forwarded the request to.
How do I fix 502 Bad Gateway in nginx?
Check that the upstream app is running on the address in proxy_pass, then read the nginx error log for the exact upstream failure.
What is the difference between 502 and 504?
502 means the upstream sent a bad response or the connection failed. 504 means the upstream did not respond in time.
See also
Header and content rules
RFC 9110 adds no header or content rule specific to 502. The 5xx class rules also apply. See 502 in the response obligations table.