503 Service Unavailable vs 504 Gateway Timeout

503 = 'I am temporarily unable to serve' (capacity issue, planned maintenance). 504 = 'I tried to forward upstream but got no answer in time'. Confusion masks real cause.

intermediate RFC 7231 §6.6.4 (503), §6.6.5 (504)

What the RFC says

The 503 (Service Unavailable) status code indicates that the server is currently unable to handle the request due to a temporary overload or scheduled maintenance, which will likely be alleviated after some delay. (RFC 7231 §6.6.4) — RFC 7231 §6.6.4 (503), §6.6.5 (504)

Example

GET /api/data HTTP/1.1
Host: api.example.com

# Server itself is overloaded:
HTTP/1.1 503 Service Unavailable
Retry-After: 30

# Or — server fine, upstream not responding:
HTTP/1.1 504 Gateway Timeout

Real-world implementations

Nginx returns 504 when proxied upstream doesn't respond within `proxy_read_timeout` (default 60s).
Cloudflare returns 503 with their branded page when origin is overloaded; 504 when origin isn't responding at all.
Heroku returns 503 during deploys (`H10 — App crashed`).

Common misuses (don't do this)

Using 500 for everything — masks real failure modes (capacity vs upstream vs bug).
Returning 504 from your origin — by definition you ARE the origin, you shouldn't say 'gateway timeout'. Use 503.
Forgetting `Retry-After` on 503 — clients retry immediately, worsening the overload.

Use cases

Outage triage (capacity vs dependency vs bug)
Load balancer / reverse proxy configuration
Maintenance window response handling
Dependency failure modeling

Get the RFC reference for any HTTP response

httpwut takes a curl response and explains the status code + headers + the RFC sections you should actually read. Built for HTTP debugging that goes deeper than 'lol 500'.

Open httpwut