502 vs 503: What Is the Difference?

502 vs 503: What Is the Difference?

A 502 means one server asked another server and got a broken answer back. A 503 means the server received your request and cannot handle it right now.

Both are 5xx, so both are the server's problem rather than yours. But they point at different parts of the stack, and confusing them sends you debugging the wrong thing.

01The One-Line Version

502 Bad Gateway: the front door is fine, something behind it is not.

503 Service Unavailable: the front door itself is turning you away.

A 502 always involves at least two servers: a proxy, load balancer or CDN in front, and an origin behind it. A 503 can come from a single server that is overloaded or in maintenance.

02Where Each Comes From

03The Five Common Causes of a 502

1. The application behind the proxy is not running. Nginx is up, your Node process is not. The most common cause by a distance.
2. The upstream crashed mid-request. The app accepted the connection and died before responding.
3. A timeout between proxy and origin. The origin is working but slower than the proxy's patience, so the proxy gives up and reports a bad gateway.
4. A misconfigured upstream. Wrong port, wrong host, wrong socket path. Very common right after a deployment.
5. A malformed response. The origin returned something that is not valid HTTP, which some proxies reject as a bad gateway.

04The Four Common Causes of a 503

1. Overload. More traffic than capacity. The server is choosing to shed load rather than fall over.
2. Deliberate maintenance. Many frameworks have a maintenance mode that returns 503 with a Retry-After. This is correct behaviour, not a fault.
3. A failing health check. The load balancer has no healthy backends to route to, so it returns 503 rather than trying.
4. A dependency is down. The app is running but a database or critical service is not, and it returns 503 rather than pretending to work.

That second one matters. A 503 during a deploy is the system behaving correctly. Alerting on every 503 without checking whether a deploy is running produces noise.

05What To Do About Each

Getting a 502 as a client: retry with backoff. It is usually transient and often resolves within seconds as the upstream restarts. If it persists for minutes, the origin is genuinely down and no amount of retrying helps.

Getting a 502 as an operator: check whether your application process is running first, then the proxy's upstream configuration, then timeouts. The proxy error log names the upstream it failed to reach, which is usually the whole answer.

Getting a 503 as a client: check for Retry-After and honour it. A 503 with a Retry-After is a server that expects to be back, and it has told you when.

Getting a 503 as an operator: find out whether it is capacity, a deploy, or a failed health check. Those are three different fixes and the load balancer's health status usually distinguishes them.

06502 and 503 vs 500 and 504

The neighbours, briefly:

500 Internal Server Error is an unhandled exception in the application. One server, code that threw. Not transient, and retrying rarely helps.

504 Gateway Timeout is the close relative of 502: a proxy waited for an upstream and gave up. The difference is that a 502 got a bad answer, while a 504 got no answer in time.

If you see 502 and 504 together in a burst, the origin is probably struggling rather than dead.

07A Worked Example

You deploy at 14:00. Between 14:00 and 14:02 your monitoring shows a spike of 502s, then it clears.

That is the old process stopping before the new one is ready to accept connections. The proxy is up throughout and briefly has nothing healthy behind it.

The fix is not retry logic. It is a graceful deploy: start the new process, wait for its health check to pass, then drain and stop the old one. Handled properly, the same deploy produces zero 502s.

If you had seen 503s instead, that would suggest the load balancer knew it had no healthy backends, which is the better failure mode of the two.

08FAQ

What is the difference between 502 and 503?

A 502 means a proxy or gateway received an invalid response from an upstream server. A 503 means the server itself cannot handle the request right now, usually from overload or maintenance.

Is a 502 my fault or the server's?

The server's. All 5xx codes indicate a problem on the server side. Your request was valid and something behind the scenes failed to answer properly.

Should I retry a 502 or 503?

Yes, both are usually transient. Use exponential backoff, and if a 503 includes a Retry-After header, honour it rather than guessing.

What causes a 502 Bad Gateway?

Most often the application behind the proxy is not running or crashed mid-request. Other causes are timeouts between proxy and origin, a misconfigured upstream address or port, and malformed responses.

What is the difference between 502 and 504?

Both involve a proxy failing to get a usable response from an upstream. A 502 means it got an invalid response; a 504 means it got no response before the timeout expired.

Why do I get 502 errors after deploying?

Usually because the old process stopped before the new one was ready to serve. The proxy stays up with nothing healthy behind it. A graceful deploy that waits for the new process's health check fixes it.

Is a 503 always a problem?

No. Maintenance mode returns 503 deliberately, and it is the correct code for a planned outage. A 503 with a Retry-After is the server communicating properly rather than failing.

09Related

• What Does 429 Too Many Requests Mean? - the 4xx cousin, and why the fix is different
• 405 Method Not Allowed - when the problem is the verb, not the server
• API Fundamentals - status codes from scratch

Source: RFC 9110, section 15.6

10About ApyHub

ApyHub is a curated API catalog for developers, teams and AI agents: file conversion, data validation, OCR and extraction and more across 20 categories. One key covers all of it, every endpoint is MCP-ready so AI agents can discover and call them directly, and every service page has a playground for testing before you build.

EU-based and EU-hosted, which keeps data residency simple for teams with GDPR obligations.

Browse the catalog | Get a free API key - no credit card required.