You click on a link or load a page, and instead of the site, you get an error message: 502 Bad Gateway. No explanation, no context, just that message. It looks like the server is there, but somewhere along the way something goes wrong. And it does.
A 502 error means that a server acting as an intermediate station (for example, a proxy or gateway) is not getting a valid response from another server it relies on. That server could be your backend, an external API or even a database interface, for example. So it is neither a front-end error nor a crash in your own code, but something in between.
What exactly is an http 502?
The http status code 502 falls under the 5xx series, or server-side errors. But unlike a 500 internal server error, 502 more specifically indicates communication problems between servers.
Imagine Internet traffic as a passing chain: browser → proxy → app server. If step two passes the ball to step three, but doesn't get a clear response back, it says, "502, I can't process this."
Sometimes you get the error in the form of:
502 Bath Gateway
The server was acting as a gateway or proxy and received an invalid response from the upstream server.
Typical causes of a 502 error
The error may be caused by:
- A backend server that is down or slow to respond
- An incorrect configuration of your reverse proxy (e.g. NGINX or Apache)
- A timeout in communication between servers
- DNS problems, especially after recent changes in hosting
- Blockages caused by firewalls or load balancers
- External APIs that are not easily accessible
The tricky part is that sometimes it is only temporary. A heavy spike in traffic may be just enough to make a server briefly unreachable, preventing the proxy from getting a valid response back. But if the error persists, you really need to start digging.
How do you find this error?
If your website suddenly returns a 502 notification, you can often find it in tools such as Screaming Frog. During crawling, that tool can indicate exactly which URLs return a 502 status code. Curl or Postman also return this nicely in the response headers.
For JavaScript-based apps or fetch calls, you'll see notifications like:
request failed with status code 502
... or in conjunction with Axios:
axioserror: request failed with status code 502
What can you do about it?
Some technical checks:
- Restart your backend services. If a process crashes, a restart can work wonders.
- Check to see if the app server is responding. Make a direct request to the backend endpoint, outside the proxy.
- Check your proxy configuration. In NGINX: are the proxy_pass settings correct? Is the upstream working?
- Log your error details. Look in your server logs: NGINX's error.log, PHP-FPM logs, or logs from your appframework.
- Test DNS resolution. Try resolving the IP manually. Errors sometimes occur after migrations or DNS changes.
- Check firewall or CDN rules. Especially if you use Cloudflare or another caching layer, blockages can occur. Sometimes Cloudflare even causes a related 520 error for unknown problems.
Final thought
A 502 http status code is frustrating because it doesn't give you much of an explanation, just a symptom. But behind that symptom is a technical communication problem. Intermediate layers such as proxies, API gateways or CDNs lose their connection to a source server.
So don't think of a 502 error as the endpoint, but as an intermediate message that tells you where to look: between frontend and backend. The ball is being played, but no one is catching it.
A well-established monitoring stack, clear logging and the occasional Screaming Frog crawl help to spot these kinds of errors faster, and hopefully fix them before your users see them.
