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-After may be present.
  • 504: the upstream is reachable but slower than the gateway's timeout.

Example response

http
HTTP/1.1 502 Bad Gateway
Server: nginx

HTTP/1.1 503 Service Unavailable
Retry-After: 120

HTTP/1.1 504 Gateway Timeout
Server: nginx

Why 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.