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.