502 and 503: the proxy is telling the truth
Updated
Bad gateway means the proxy is fine and upstream is not: check upstream health, then the proxy config, in that order.
A 502 page feels like the proxy broke. It is the opposite: the proxy works fine and is reporting that upstream failed it. Restarting the proxy for a 502 is like replacing the messenger for bad news.
Upstream first, config second
Ask upstream directly. Bypass the proxy and query the backend on its own address. Connection refused means the backend is down; a slow answer means it is sick; a good answer means the proxy path is the suspect.
Then read the proxy config. Upstream address, port, timeouts and health checks. Most 502s are a wrong port after a deploy, a timeout shorter than the backend needs, or a health check nobody wired.
Worked example: a fictional checkout proxy
The context below is fictional. Fictional proxy in front of BrightCart checkout (fictional) starts serving 502 on every payment call after a backend deploy. The proxy logs name the upstream address and the refused connection.
Direct query to the backend refuses too: the new version listens on a different port than the proxy config names. The fix is one port number in the proxy config, proven by backend-healthy then proxy-200. The prevention is a deploy checklist line: confirm the listening port before routing traffic.
Decision table: gateway errors
| Code | Meaning | First move |
|---|---|---|
| 502 | Upstream bad or unreachable | Query upstream directly |
| 503 | Something unavailable | Check who marked it down and why |
| 504 | Upstream too slow | Compare backend latency with proxy timeout |
Related reading
- Hands on: Proxy Upstream 502 and 503.
- DevOps Foundations Module 2 covers HTTP behind proxies.
Straight answers
Frequently asked questions
502 or 503, which is worse?
Neither by itself. 502 says upstream answered badly or not at all; 503 says something is unavailable, often on purpose. The next step is the same: look upstream.
Should I restart the proxy first?
No. The proxy produced the error page, so it works. Restarting it destroys evidence and rarely helps.
What proves the fix?
Upstream healthy by its own check, then the same request through the proxy returning 200.