502 Bad Gateway proxy error: find who sent it, then fix it

Originally published on proxymint.

A 502 through a proxy comes from the proxy or from the target's own gateway. How to tell them apart in one command, what causes each, and when to retry.

TL;DR

• A 502 always comes from a server in the middle. RFC 9110 defines it as a gateway or proxy that got an invalid answer, or none, from the next server, so the job is finding which middle server sent it.
• The CONNECT layer tells you who. On an https:// target, a 502 that answers the CONNECT came from the proxy and the site never saw the request. A 502 that arrives inside the open tunnel came from the site's CDN or load balancer.
• Clients report a CONNECT 502 as an error string. curl says CONNECT tunnel failed, response 502; Python says Tunnel connection failed: 502; Chromium shows ERR_TUNNEL_CONNECTION_FAILED and hides the code.
• Retry depends on the layer. A CONNECT 502 is safe to retry for any method through another exit; a 502 from the site is retried only for idempotent methods, with backoff.

Key takeaways

• Run curl -v through the proxy before changing anything. A 502 right after the CONNECT line is the proxy; a 502 after the TLS handshake is the target.
• Read Proxy-Status when it is there. RFC 9209 error types such as dns_error, connection_refused and connection_terminated name the cause and the hop in one header.
• Let rotation do the retry. With a new IP on every request a retry leaves through another exit; on a sticky session, a run of 502s on one session points at that exit.
• Back off when the 502 follows the host. The same hostname failing on every exit, or a branded 502 page, means the site is down: wait minutes, not seconds.

Read the full guide on proxymint, with the commands, tables and sources.