HTTP 502 Bad Gateway

What HTTP 502 means

502 Bad Gateway happens at the proxy layer. A reverse proxy or load balancer (nginx, a CDN, an API gateway) forwarded your request to an upstream server, but got back something invalid — or nothing usable. The proxy itself is fine; the upstream is the problem.

Common causes

• The upstream server is down or crashed
• The upstream returned a malformed response
• A reverse proxy is misconfigured (wrong upstream address/port)
• The upstream timed out or reset the connection

Example JSON error response

{
  "error": "Bad Gateway",
  "message": "The upstream server returned an invalid response.",
  "status": 502
}

Raw HTTP response

HTTP/1.1 502 Bad Gateway
Content-Type: application/json

How to troubleshoot HTTP 502

• ✓ Check the upstream/origin server is running and healthy
• ✓ Verify the reverse proxy points at the correct upstream address and port
• ✓ Inspect upstream logs for crashes or malformed responses
• ✓ Check upstream timeout and keep-alive settings
• ✓ Confirm the upstream is not being restarted or redeployed

502 vs 503 vs 504 — what's the difference?

502 Bad Gateway: the proxy got an invalid response from the upstream. 503 Service Unavailable: the server is up but temporarily can't handle the request (overload/maintenance). 504 Gateway Timeout: the upstream didn't respond in time. 502 = bad response, 503 = not available, 504 = too slow.

Why a 502 is usually not your client's fault

A 502 almost always means the request never reached a healthy application — it died at the proxy/upstream boundary. That's why a 502 often has an HTML body from nginx or the CDN rather than your API's JSON: your app never got to format a response. If you're calling an API and see a 502, the fix is rarely in your request; it's a transient upstream problem, so retry with backoff:

const res = await fetch('/api/data');

// 502 is typically transient (upstream restarting/redeploying)
if (res.status === 502 || res.status === 503 || res.status === 504) {
  return retryWithBackoff(() => fetch('/api/data'), { max: 3 });
}

// don't assume JSON on a 502 — proxies often return an HTML error page
const type = res.headers.get('Content-Type') || '';
const body = type.includes('application/json') ? await res.json() : await res.text();

Common 502 causes if you run the server