HTTP 502 Bad Gateway – Free, Online, Private

What HTTP 502 means

502 says this server, acting as a gateway or proxy, received an invalid response from the upstream it contacted. The connection may have reset, the upstream may have spoken the wrong protocol, or the status line may have been garbage. The client asked the gateway, and the gateway is reporting that the next hop failed. It is not the same as the origin returning 500, which is a valid response the gateway would forward.

502 Bad Gateway belongs to the 5xx server error class. Clients that only look at the class will group it with its neighbors. Clients that care about the exact code should use the narrower rule on this page, because the class is only the first digit.

When you see HTTP 502

When you see HTTP 502 Bad Gateway, stop on that exact status line. 502 Bad Gateway means a proxy got an invalid response from the upstream. The trace that usually produces it: The upstream closed the connection without a status line. The 5xx server error class only tells you the first digit. A neighbor in that class is a different fault, and the fix on this page does not transfer to it.

Return 502 when you are a gateway and the upstream response was unusable. If the upstream timed out, 504 is more specific. If you are the origin and your own code threw, return 500. Do not let a gateway rewrite an origin 500 into 502. That hides the bug.

How to fix HTTP 502

To fix HTTP 502, change the condition that made the server choose Bad Gateway. Retry an idempotent request with backoff. If 502s persist, the upstream is broken and more retries will not help. Show a gateway error rather than parsing the body as application JSON unless you know the gateway's format. Yes for safe methods, with backoff and a limit. No for a tight loop. POST only with an idempotency key. If the log line is a different code, leave this page. The mix-up people make with 502 is this one: 500 is the origin's own failure, forwarded as 500. 504 is a timeout waiting for the upstream. 503 is a deliberate refusal. 502 is an invalid upstream response.

• A deploy restarted the upstream in the middle of a response.
• The upstream spoke HTTP/1.0 garbage the gateway would not pass on.
• A health check treated 502 as 'origin is down' when only one route's upstream was misconfigured.

An access log that only stores 502 is not enough to tell these apart. Keep the method, the path, and a request id. Do not keep the Authorization header or a request body that might be a token. The status explains the outcome. It is not a place to echo secrets back to the client either.

Example response

HTTP 502 Bad GatewayHTTP/1.1 502 Bad Gateway
Content-Type: text/plain

Bad gateway

The body is from the gateway, not from the application. Look at the gateway log for the upstream error. Retrying a GET may succeed if a replica is healthy. Retrying will not fix a bad configuration that breaks every request.

What the client should do

Retry an idempotent request with backoff. If 502s persist, the upstream is broken and more retries will not help. Show a gateway error rather than parsing the body as application JSON unless you know the gateway's format.

Do not cache 502 as the resource. A short outage would stick.

Yes for safe methods, with backoff and a limit. No for a tight loop. POST only with an idempotency key.

Codes people confuse with HTTP 502

500 is the origin's own failure, forwarded as 500. 504 is a timeout waiting for the upstream. 503 is a deliberate refusal. 502 is an invalid upstream response.