HTTP 502 Bad Gateway

HTTP 502 Bad Gateway — A gateway or proxy got an invalid response from the upstream server.

Class

5xx Server Error

Defined in

RFC 9110 §15.6.3

Official

Yes (IANA registry)

Cacheable by default

No (unless Cache-Control/Expires say so)

Safe to retry

Yes, after a delay (respect Retry-After)

What does HTTP 502 mean?

502 Bad Gateway means a server acting as a gateway or proxy (nginx, a load balancer, a CDN) received an invalid response from the upstream server it forwarded the request to — or couldn't get a usable response at all.

The proxy itself is working; the problem lies behind it: the application server crashed, isn't running, closed the connection, or returned something that isn't valid HTTP.

When is 502 used?

• nginx can't connect to your app ("connect() failed (111: Connection refused) while connecting to upstream").
• The app crashes mid-request or closes the connection ("upstream prematurely closed connection").
• Response headers are too large for the proxy's buffers ("upstream sent too big header").
• PHP-FPM, Gunicorn or Node isn't running, or listens on a different port/socket than configured.
• AWS ALB/API Gateway: the Lambda or target returned a malformed response.

Common causes of a 502

• The application server is down, restarting or out of memory.
• Wrong upstream address or port in the proxy config.
• Firewall or security group blocking the proxy from reaching the backend.
• Upstream timeouts shorter than the app's response time in some setups (often 504 instead).
• Large cookies/headers overflowing proxy_buffer_size.

How to fix 502 Bad Gateway

If you're visiting the site

1. Reload after 30–60 seconds; 502s are often brief, e.g. during a deploy.
2. Check status pages or downdetector to see if the outage is widespread.
3. Clear cache and cookies, or try another browser or network if only you see it.

If you run the site or API (developers)

1. Read the proxy's error log — it states exactly why the upstream failed.
2. Check the app is running and listening where the proxy points (ss -ltnp, systemctl status, container health).
3. Look for crashes and OOM kills in app logs (dmesg | grep -i kill).
4. Increase proxy_buffer_size/proxy_buffers if the log says the upstream header is too big.
5. Use health checks and zero-downtime deploys so the proxy never routes to a dead instance.

Returning or handling 502: server examples

upstream app { server 127.0.0.1:3000; keepalive 32; }

server {
    location / {
        proxy_pass http://app;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_buffer_size 16k;   # fixes "upstream sent too big header"
        proxy_buffers 8 16k;
    }
}
# Diagnose: tail -n 50 /var/log/nginx/error.log

// Make sure Node listens on the address nginx proxies to
app.listen(3000, "127.0.0.1", () => console.log("listening on :3000"));

// Keep-alive must outlive the proxy/LB idle timeout (ALB default 60s),
// otherwise reused connections are closed → sporadic 502s.
server.keepAliveTimeout = 65_000;
server.headersTimeout = 66_000;

// When self-hosting behind nginx, run the production server:
//   next build && next start -p 3000
// A 502 usually means the Node process isn't running or crashed —
// check your process manager:  pm2 logs  /  docker logs <container>

Example 502 response

HTTP/1.1 502 Bad Gateway
Server: nginx
Content-Type: text/html
Content-Length: 150

<html><head><title>502 Bad Gateway</title></head><body><center><h1>502 Bad Gateway</h1></center></body></html>

502 vs 503 vs 504

All three come from the server side. 502: the proxy got a broken response (or connection failure) from upstream. 503: the service says it's temporarily unavailable — overload, maintenance or no healthy backends. 504: the proxy waited and the upstream never answered in time. On Cloudflare, the equivalents with more detail are 520–524.

Related status codes

• 504 Gateway TimeoutA gateway or proxy didn't get a response from the upstream server in time.
• 503 Service UnavailableThe server is temporarily unable to handle the request (overload or maintenance).
• 520 Web Server Returned an Unknown ErrorCloudflare got an empty, unknown or unexpected response from the origin server.

Related tools

• HTTP status codes — full list
• HTTP headers reference
• cURL converter
• Mock API — fake REST endpoints with custom status codes
• Webhook tester — inspect incoming requests