DevToolsmith

HTTP 502 Bad Gateway

HTTP 502 Bad Gateway means a proxy or gateway got an invalid response from the upstream server. The server failed to fulfil a valid request. The problem is on the server side.

Class
5xx Server error
Standard
RFC 9110
Cacheable by default
No
Safe to retry
Yes, usually
Go constant
http.StatusBadGateway

What HTTP 502 means

Something in front of your app (nginx, a load balancer, Cloudflare, an API gateway) tried to reach the backend and got garbage or nothing: the connection was refused or reset, or the response was malformed. The proxy is working; the server behind it isn’t.

How to fix a 502 error

  • Check that the backend is running and listening on the port the proxy uses: curl -v http://127.0.0.1:3000 from the proxy host.
  • In Docker, the app must listen on 0.0.0.0, not 127.0.0.1, to be reachable from other containers.
  • nginx logs the exact cause in error.log, e.g. “connect() failed (111: Connection refused)” or “upstream prematurely closed connection”.
  • PHP-FPM crashes, out-of-memory kills and deploys that restart the app all cause short bursts of 502.

Retrying

Yes, usually. It is often temporary, so retry with exponential backoff and give up after a few attempts.

Example response

HTTP/1.1 502 Bad Gateway
Date: Wed, 21 Oct 2026 10:30:00 GMT
Content-Type: application/json

How to return 502

Node.js (Express)
res.status(502).json({ error: 'Bad Gateway' });
Python (FastAPI)
from fastapi import HTTPException

raise HTTPException(status_code=502, detail="Bad Gateway")
Go (net/http)
http.Error(w, http.StatusText(http.StatusBadGateway), http.StatusBadGateway)
nginx
location /private/ {
    return 502;
}

Related status codes

Other 5xx status codes

500 Internal Server Error · 501 Not Implemented · 503 Service Unavailable · 504 Gateway Timeout · 505 HTTP Version Not Supported · 507 Insufficient Storage · 508 Loop Detected · 511 Network Authentication Required · 520 Web Server Returned an Unknown Error · 521 Web Server Is Down · 522 Connection Timed Out · 523 Origin Is Unreachable · 524 A Timeout Occurred · 525 SSL Handshake Failed · 526 Invalid SSL Certificate

See the full list of HTTP status codes.

Sources

Spotted a mistake? Email hello@devtoolsmith.com and we’ll fix it.

Frequently asked questions

What does HTTP 502 Bad Gateway mean?

HTTP 502 Bad Gateway means a proxy or gateway got an invalid response from the upstream server. Something in front of your app (nginx, a load balancer, Cloudflare, an API gateway) tried to reach the backend and got garbage or nothing: the connection was refused or reset, or the response was malformed. The proxy is working; the server behind it isn’t.

How do I fix HTTP 502?

Check that the backend is running and listening on the port the proxy uses: curl -v http://127.0.0.1:3000 from the proxy host. In Docker, the app must listen on 0.0.0.0, not 127.0.0.1, to be reachable from other containers. nginx logs the exact cause in error.log, e.g. “connect() failed (111: Connection refused)” or “upstream prematurely closed connection”. PHP-FPM crashes, out-of-memory kills and deploys that restart the app all cause short bursts of 502.