What 502, 503, and 504 Errors Really Mean (And How to Fix Them)

Your site shows a scary number: 502, 503, or 504. These look similar but mean very different things. Here's what each actually means and how to fix them.

502 Bad Gateway

What it means: Your web server (usually Nginx or Apache) tried to talk to your app — and the app refused the connection or sent back garbage.

Most common causes:

• Your app crashed and isn't running
• Your app is still starting up after a deploy
• Your app is running on a different port than Nginx thinks
• Your app is running but returned something malformed

How to fix:

1. Check that your app is actually running:
2. ```
3. sudo systemctl status your-app
4. ```
5. Check app logs for crashes:
6. ```
7. sudo journalctl -u your-app -n 100
8. ```
9. Verify the port matches what Nginx expects (proxy_pass in your Nginx config)
10. If you just deployed, wait 30 seconds — the app may still be booting

503 Service Unavailable

What it means: Your web server is running, but it's *intentionally* refusing requests. Either in maintenance mode, overloaded, or has no healthy upstream to send traffic to.

Most common causes:

• Maintenance mode is enabled (someone flipped the switch)
• All upstream app servers are down (load balancer has nowhere to send traffic)
• Rate limiting is kicking in
• Cloudflare/CDN is showing a "try again" page

How to fix:

1. Check for maintenance flag files (.maintenance, maintenance.html)
2. Check upstream health — are your app servers actually up?
3. Check rate limit rules in Nginx/Apache/Cloudflare
4. Check if a CDN in front is the one returning 503 (look at response headers for server: cloudflare)

504 Gateway Timeout

What it means: Your web server tried to talk to your app — the app *started* responding but didn't finish in time.

Most common causes:

• Your app is very slow (slow database query, external API timeout)
• Your app is stuck in a loop
• Database is overloaded
• Timeout in Nginx is set too low for a legitimately slow operation

How to fix:

1. Check app response times — something has gotten slow
2. Look for slow database queries:
3. ```
4. SHOW FULL PROCESSLIST; # in MySQL
5. ```
6. Check if your app is doing synchronous work that should be queued (sending email, processing files, calling external APIs)
7. If the operation is *legitimately* long (file upload, report generation), raise the timeout:
8. ```
9. proxy_read_timeout 300s; # in Nginx
10. ```

How to tell which layer is causing it

Every 502/503/504 comes from *some* layer. Check response headers:

`` curl -I https://yoursite.com ``

• Look at the server header:
• cloudflare → Cloudflare is returning the error
• nginx or Apache → your web server
• Custom header like AWS-ALB → your load balancer

Fix it at the right layer — a Cloudflare 502 isn't your server's fault.

Prevention

• Health checks: Most load balancers and CDNs will automatically stop sending traffic to unhealthy backends if you set up health check endpoints
• Monitoring: Uptime monitors with HTTP status code alerting (UptimeRobot is free)
• Graceful deploys: Use zero-downtime deployment so 502s don't appear every time you push
• Queue long work: Anything over ~10 seconds should be async, not synchronous

Need help?

I fix gateway errors regularly — most take under an hour. If your site is erroring right now, send me a message with what the error page says and I'll help.