DEV Community

upordown.online
upordown.online

Posted on Edited on

503 vs 504: what each error means and who has to fix it

#http #webdev #devops #debugging

503 Service Unavailable and 504 Gateway Timeout both mean "the site isn't working right now", and people often treat them as the same thing. They aren't. Each one points at a different part of the stack, and knowing which one you got tells you where to look and whether waiting will help.

503 Service Unavailable

A 503 means the server received your request and decided not to serve it. The important part is that something answered on purpose.

Common reasons:

  • Maintenance mode. Many apps and CMSs return 503 while an update runs. This is the correct code for planned downtime because it tells search engines to come back later.
  • Overload. The server or its worker pool is full, so new requests are turned away instead of queued forever.
  • No healthy backends. A load balancer returns 503 when every server behind it is failing health checks.
  • Rate limiting or protection. Some setups use 503 (others use 429) when a client sends too many requests.

A well-behaved 503 often includes a Retry-After header:

HTTP/1.1 503 Service Unavailable
Retry-After: 300
Enter fullscreen mode Exit fullscreen mode

That's the server saying "try again in five minutes".

504 Gateway Timeout

A 504 comes from a proxy, CDN or load balancer sitting in front of the real application. It forwarded your request upstream, waited, and gave up because no answer arrived in time.

So with a 504, the thing that answered you is working fine. The thing behind it is slow or stuck. Typical causes:

  • A slow database query or a locked table
  • An application process that hangs on an external API call
  • An upstream server that is down in a way that leaves connections open
  • A proxy timeout that is shorter than a legitimately long request (big exports, report generation)

How to tell where the error came from

Look at the response headers and the error page:

curl -sI https://example.com/ | grep -iE '^(HTTP|server|via|cf-ray|x-cache|retry-after)'
Enter fullscreen mode Exit fullscreen mode
  • server: cloudflare and a cf-ray header: the response came from Cloudflare's edge. A Cloudflare-branded 504 page means the origin was too slow.
  • server: nginx with a plain page: often nginx acting as a reverse proxy in front of an app server.
  • via headers list proxies the request went through.

If the error page has the CDN's branding, the CDN is up and your origin is the problem.

If you run the site

For a 503:

  1. Check whether a deploy or maintenance mode is stuck. A leftover maintenance flag file is a classic.
  2. Look at the load balancer's health check status. If all targets are unhealthy, find out why the check fails.
  3. Check worker or process limits (PHP-FPM pm.max_children, Gunicorn workers, connection pool size). If they are maxed out, you're overloaded.

For a 504:

  1. Find the slow request in your app logs or APM, and see what it was waiting on.
  2. Compare timeouts at each layer. If the CDN gives up after 100 seconds and nginx after 60, the shorter one wins.
  3. In nginx, the relevant settings are: 
location / {
    proxy_pass http://app;
    proxy_connect_timeout 5s;
    proxy_read_timeout 60s;
}
Enter fullscreen mode Exit fullscreen mode

Raising proxy_read_timeout hides the symptom. It's fine for genuinely long tasks, but for normal page loads, fix the slow query or move the work to a background job.

If you're a visitor

  • 503: wait and retry. If there's a Retry-After, respect it. Maintenance usually ends within minutes.
  • 504: reloading sometimes works if the slowness is intermittent. If a specific action keeps timing out (a big search, an export), try a smaller version of it.

Neither error is caused by your browser, cache or DNS. Clearing cookies won't help. The request reached the site; the site just couldn't finish it.

Is it everyone?

Both errors can be partial. One region's servers can be overloaded while another's are fine, or only one backend might be stuck. Checking from more than one place helps. upordown.online tests the address from its own server, keeps an outage log for popular services, and shows what other people are reporting, so you can see whether a 503 is widespread or just your corner of the internet.

Quick comparison

503 504
Who answered The server or its load balancer A proxy, gateway or CDN
What it means "I won't serve this right now" "The server behind me didn't answer in time"
Common cause Maintenance, overload, no healthy backends Slow app, slow database, hung upstream
Will waiting help Usually Sometimes
Visitor can fix it No No

Related reading

Top comments (0)