TL;DR: 502 means the upstream sent something unusable or hung up on the proxy. 504 means the upstream never answered before the proxy’s timer ran out. 503 means a server deliberately said “not now” because of overload, maintenance or a limit. Read the proxy’s error log line: it names which of the three happened and which upstream did it.
The Three In One Table
| 502 Bad Gateway | 503 Service Unavailable | 504 Gateway Timeout | |
|---|---|---|---|
| Who generates it | A proxy, gateway or CDN | The origin, or a proxy/LB acting on policy | A proxy, gateway or CDN |
| What the upstream did | Refused, reset, closed early or sent an invalid response | Nothing wrong with the wire; it (or the LB) chose to refuse | Accepted the connection but did not answer in time |
| Spec | RFC 9110 15.6.3 | RFC 9110 15.6.4 | RFC 9110 15.6.5 |
Retry-After expected | No | Optional, often useful | No |
| Usual root cause | App crashed, wrong port or socket, keep-alive race, oversized headers | Overload, deploy drain, no registered targets, rate or connection limit | Slow query, blocked worker, timeout shorter than the work |
| nginx error log | connect() failed (111: Connection refused), upstream prematurely closed connection, recv() failed (104: Connection reset by peer) | limiting requests, excess: ... (limit_req) or limiting connections by zone (limit_conn) | upstream timed out (110: Connection timed out) while reading response header from upstream |
| Cloudflare cousins | 502, 520, 521, 523 | 503 (from your origin or Cloudflare) | 504, 522, 524 |
| Detail pages | 502, nginx 502 fix | 503 | 504, nginx 504 fix |
Step 1: Who Sent It
Before reading any log, work out which layer produced the status. A 5xx from your app and a 5xx from the proxy in front of it look identical in a browser.
curl -sS -D - -o /dev/null https://example.com/api/slow
Things to look at in the headers and body:
Server: nginxwith a plain centered “502 Bad Gateway” body: nginx generated it. Your app may not have been reached.Server: cloudflareplus aCF-Rayheader, and a branded error page with a numeric code (520-526): Cloudflare generated it, and the code tells you what happened between Cloudflare and your origin.Server: awselb/2.0: an AWS Application Load Balancer. Its 502, 503 and 504 appear in the ALB access log withelb_status_codeset andtarget_status_codeset to-when the target never responded.- Your framework’s own error format (JSON from your API, a Django or Rails page): the application produced it. Check the app log, not the proxy.
Step 2: What The Upstream Did
nginx writes one error-log line per failure with the upstream address, and that line almost always settles it.
2026/10/04 09:12:31 [error] 2841#2841: *9087 connect() failed (111: Connection refused) while connecting to upstream, client: 203.0.113.9, server: example.com, request: "GET /api/orders HTTP/1.1", upstream: "http://127.0.0.1:3000/api/orders", host: "example.com"
connect() failed (111: Connection refused) means nothing is listening on that port. The app is down, crashed or bound to a different address: 502.
2026/10/04 09:14:02 [error] 2841#2841: *9102 upstream prematurely closed connection while reading response header from upstream, upstream: "http://127.0.0.1:3000/api/orders"
The upstream accepted the request and closed the socket without a response. A worker was killed (OOM, max_requests recycling) or a keep-alive connection was reused after the app closed it: 502.
2026/10/04 09:15:47 [error] 2841#2841: *9130 upstream timed out (110: Connection timed out) while reading response header from upstream, upstream: "http://127.0.0.1:3000/api/report"
The upstream connected but sent no response header within proxy_read_timeout, which defaults to 60 seconds: 504. If the line ends with while connecting to upstream, it hit proxy_connect_timeout (also 60s by default), meaning the host is unreachable or its accept queue is full.
2026/10/04 09:16:20 [error] 2841#2841: *9144 limiting requests, excess: 5.420 by zone "perip", client: 203.0.113.9
This is nginx deliberately rejecting traffic with limit_req, which answers 503 unless you set limit_req_status 429;. Not an upstream fault at all.
Step 3: Cloudflare And Load Balancer Equivalents
| What happened | nginx says | Cloudflare shows | AWS ALB |
|---|---|---|---|
| Origin refused the connection | 502, Connection refused | 521 Web Server Is Down | 502 |
| Origin closed the connection or replied with garbage | 502, prematurely closed | 520 Web Server Returned an Unknown Error | 502 |
| TCP connect to origin timed out | 504, while connecting to upstream | 522 Connection Timed Out | 504 |
| Origin took too long to respond | 504, while reading response header | 524 A Timeout Occurred (100 s by default on non-Enterprise) | 504 once the idle timeout (60 s default) expires |
| No route to origin | n/a | 523 Origin Is Unreachable | n/a |
| TLS failure toward origin | 502, SSL_do_handshake() failed | 525 SSL Handshake Failed, 526 Invalid SSL Certificate | 502 |
| Deliberate shedding or maintenance | 503 | 503 passed through from origin | 503 when the target group has no registered targets |
Per-code pages: 520, 521, 522, 523, 524, 525, 526.
Which Should I Return From My Own Gateway
If you write a reverse proxy, API gateway or BFF, the spec guidance maps directly:
HTTP/1.1 502 Bad Gateway
Content-Type: application/json
{"error": "upstream_invalid_response", "upstream": "orders"}
Use 502 when you reached the upstream and its response was unusable or the connection failed. Use 504 when you waited and the deadline passed. Use 503 when you chose to refuse, for example a circuit breaker is open or a queue is full, and add Retry-After:
HTTP/1.1 503 Service Unavailable
Retry-After: 30
Content-Type: application/json
{"error": "overloaded"}
A plain application (not a gateway) that hit its own failure should usually return 500, not 502 or 504, because there was no upstream.
Common Mistakes
Raising proxy_read_timeout to fix a 504 without finding the slow call. The user still waits longer, and an ALB or Cloudflare in front has its own, lower limit. A 524 at 100 seconds ignores your nginx setting.
Reading a 502 as “the app is down.” Frequently the app is up and nginx is reusing an idle keep-alive connection the app already closed (app keep-alive shorter than the proxy’s), or the response headers exceeded proxy_buffer_size (upstream sent too big header while reading response header from upstream).
Letting health checks pass while real requests fail. A /health that returns 200 without touching the database keeps the instance in rotation while every real request hangs into a 504.
Retrying non-idempotent calls after a 504. The upstream often completed the write after the proxy gave up. Retrying a payment POST without an idempotency key double-charges.
Serving 503 for maintenance without Retry-After. Crawlers and clients then guess. Send the header, and for planned maintenance keep the window short so search engines treat it as temporary.