What does HTTP status code 502 mean?
The 502 Bad Gateway status code indicates that the proxy server or gateway received an invalid or empty response from the backend application process.
When to use it in APIs
Typically generated by Nginx, Cloudflare, or AWS ALBs when the backend application node (e.g., Node.js, Python, or Go process) crashes, returns invalid headers, or is offline. Have the gateway add a Proxy-Status header naming the cause, such as error=connection_refused or error=dns_error, so you can tell those failures apart without digging through gateway logs.
How it compares to other codes
- 504 Gateway Timeout: The backend responded but took too long. 502 indicates the backend responded with garbage or terminated the connection immediately.
