When to Use 502 vs 503
502 Bad Gateway is a proxy problem: nginx, Cloudflare, an API gateway, or a load balancer received an invalid response from the upstream origin (connection reset, garbage HTTP, TLS mismatch). The origin might still be healthy for other paths.
503 Service Unavailable is the origin saying it cannot handle the request right now — overload, maintenance window, or a drained instance. It is often retryable. Send Retry-After when you know when to come back.
504 Gateway Timeout is related: the proxy waited for upstream and gave up. If you are debugging production, check proxy error logs for 502/504 and origin health for 503. The status code reference lists these next to 500 and 501.
Tips
- 502 after a deploy often means the new process is not listening on the port the proxy expects.
- 503 during a rollout can be intentional — Kubernetes readiness probes failing will take pods out of the pool.
- Do not retry 502 in a tight loop without backoff; you can amplify an outage.
- Clients should treat 503 as transient unless Retry-After says otherwise.