What 502 Bad Gateway means
502 Bad Gateway means a gateway or proxy received an invalid response from an upstream server. 503 Service Unavailable means the server is temporarily unable to handle the request, overloaded or in maintenance. 504 Gateway Timeout means the gateway did not receive a timely response from the upstream.
When a server should return it
- 502: the upstream crashed mid-response, returned malformed headers, or the connection was reset.
- 503: the service is deliberately down for maintenance or the worker pool is exhausted; a
Retry-Aftermay be present. - 504: the upstream is reachable but slower than the gateway's timeout.
Example response
HTTP/1.1 502 Bad Gateway
Server: nginx
HTTP/1.1 503 Service Unavailable
Retry-After: 120
HTTP/1.1 504 Gateway Timeout
Server: nginxWhy you might see it unexpectedly
- Deploying an app that crashes on startup, so the proxy has no healthy upstream (502).
- A load balancer sending traffic to a draining instance (503).
- A slow database query exceeding the proxy's 60-second timeout (504).
- Misconfigured TLS between the gateway and upstream (502).
- Too few workers for the request rate (503).
Related status codes
500 Internal Server Error is generated by the application itself. 408 Request Timeout is a slow client. 429 Too Many Requests is rate limiting.