502, 503, 504: Three Codes for Three Different Kinds of Broken

A 500 is the honest, boring one: something threw inside the application and nobody caught it. 502, 503, and 504 are a different family entirely — they're usually not about your application code at all, they're about the layer in front of it, and each one describes a distinct way that layer failed to get you an answer.
502 Bad Gateway: the upstream said something a proxy couldn't parse
A 502 means whatever's sitting in front of your application — a load balancer, a reverse proxy, an API gateway — successfully connected to the upstream server, but got back a response it couldn't understand or forward: garbage bytes, a connection closed mid-response, a malformed HTTP response, or nothing when it expected a valid one. The proxy isn't guessing that your app is broken; it's telling you that it, specifically, failed to relay the upstream's answer. A misconfigured app writing to the wrong port, a process crashing mid-request without closing the socket cleanly, or a proxy timeout shorter than the app expects are the classic causes.
503 Service Unavailable: temporary, and the server knows it
A 503 is a server explicitly saying "not right now" — overloaded, in maintenance, or deliberately shedding load — as opposed to 502's "I couldn't make sense of what I got back." It's meant to be temporary and, per the spec, can (and should) come with a Retry-After header telling the caller when to try again, the same as a 429. The distinction matters for automated clients: a 503 is a signal to back off and retry later, while a 502 is closer to "something is actually broken," and a retry loop that treats them identically will hammer a server that just told you it's already drowning.
504 Gateway Timeout: the upstream never answered at all
A 504 means the proxy gave up waiting — it forwarded the request to the upstream server and never got a response within its own timeout window. This is different from both 502 (got a bad response) and 503 (got an explicit "not now" response): with a 504, nothing came back at all. It's the signature of a slow database query, a downstream dependency that's itself hanging, or a proxy timeout configured shorter than the operation actually takes.
Why the difference matters more than "the API is down"
Collapsing all three into "the API is down" throws away the one piece of information that tells you where to look. A 502 points at the boundary between your proxy and your app. A 503 points at your app deliberately refusing work. A 504 points at something taking too long somewhere downstream of the proxy. Client code that treats them identically also loses something real: a 503 with Retry-After is asking to be respected, and a 504 after a long wait is a different signal than an instant 502 — one suggests retrying might help once load drops, the other suggests the operation itself may just be too slow to ever succeed within your timeout budget.
Testing that your client actually reacts differently to each
The only reliable way to confirm your error handling actually distinguishes these is to trigger all three independently and watch what the client does — which means controlling exactly which code comes back, on demand, without waiting for a real proxy or database to misbehave on schedule. MockBase's chaos scenarios let a route return any of 500, 502, 503, or 504, with an optional delay to simulate the 504's "nothing came back for a while" case specifically, versus an instant 502 or 503. Configuring three near-identical scenarios that differ only in status code turns "does my retry logic treat these three the same by accident" from a question you find out about in production into one you can watch happen in a few seconds.
Xerat02
Building MockBase.
More from the blog

400 vs 409 vs 422: Three Ways an API Says "No"
All three mean "I'm not doing that," and all three tempt a tired developer into reaching for whichever one they remember first — but they're answering three different questions about what's actually wrong with the request.

Three Ways to Fake a Dependency, and When Each One Lies to You
Mocking, service virtualization, and contract testing all answer "what do I do about a dependency I don't control" — they answer it for different problems, and using the wrong one gives you a different flavor of false confidence each time.