503 vs 504: Service Unavailable vs Gateway Timeout
503 and 504 can look similar in logs, but they tell clients, crawlers, and API consumers different things.
| Aspect | HTTP 503 — Service Unavailable | HTTP 504 — Gateway Timeout |
|---|---|---|
| Definition | The server is temporarily unable to handle the request. Unlike 500, this is usually a known, often intentional condition. The Retry-After header, when present, estimates when the server will be available. | Your reverse proxy (nginx, Cloudflare, etc.) gave up waiting for the origin server to respond within the configured timeout. The origin may be overloaded, slow, or hung. |
| Plain-language summary | The server is temporarily unable to handle the request due to overload or scheduled maintenance. Unlike 500, this is often a known, intentional state. The Retry-After header, when present, estimates when the server will be available. | A gateway or proxy timed out waiting for a response from an upstream server. The upstream received the request but did not respond within the allowed time window. This is different from 502 (upstream sent a bad response) — 504 means the upstream sent no response at all within the timeout. |
| When to use | Use 503 for: intentional maintenance windows, overload shedding when the server cannot handle more requests, circuit breaker tripping on a failing dependency. Always include Retry-After when you know the recovery time. For rate limiting a specific client, use 429 instead. | Gateways and proxies emit 504 automatically. As an application developer, tune upstream timeout configurations and optimize slow processing paths to avoid 504s. Always implement request timeouts on all outbound HTTP calls. |
| Client behavior | Retry after the time specified in Retry-After. If no Retry-After, use exponential backoff. Implement circuit breaker logic to stop sending requests to an endpoint that has been returning 503 repeatedly. | May retry — the upstream may be temporarily slow. Implement bounded retry with exponential backoff. After repeated 504s, surface the error and alert. |
| Caching behavior | May be cached if Retry-After is present, but this is unusual. Generally not cached. | Not cached. |
| SEO / crawler impact | Search crawlers interpret 503 (server-errors) for indexation and link equity accordingly. | Search crawlers interpret 504 (server-errors) for indexation and link equity accordingly. |
| API / backend impact | API clients branching on 503 expect Service Unavailable semantics. | API clients branching on 504 expect Gateway Timeout semantics. |
| Safe to retry? | Yes, with backoff — server may recover | Yes, with backoff — server may recover |
Common real-world scenarios
When you see HTTP 503
During maintenance windows, return 503 with Retry-After so users and crawlers know when to come back. During overload events, load balancers may return 503 when the upstream pool is exhausted. In microservices, a circuit breaker that has tripped returns 503 to downstream services.
When you see HTTP 504
In Nginx: "upstream timed out." In Cloudflare: <a href="/guides/cloudflare-524/">Cloudflare error 524</a> (a Cloudflare-specific timeout code). Common causes: database query that ran over the timeout threshold, external API call that was slow or hung, application code in an infinite loop or deadlock, or upstream server under high load and processing slowly.
Decision rule
Use 503 when the response should communicate service unavailable behavior; use 504 when gateway timeout is the accurate protocol signal.
A frequent mistake is swapping 503 and 504 for convenience; that causes client retry bugs, incorrect cache signals, and misleading monitoring data.
Use 503 when the correct protocol signal is Service Unavailable. Use 504 when the correct signal is Gateway Timeout. Returning either code for the wrong reason breaks client expectations, cache behavior, and monitoring accuracy.
FAQ
What is the biggest difference between 503 and 504?
503 communicates Service Unavailable, while 504 communicates Gateway Timeout. Choosing the right one keeps clients and intermediaries predictable.
Do 503 and 504 have SEO or caching impact?
Yes. Search engines and caches interpret status classes differently. Use each code according to its semantics to avoid accidental indexing, stale responses, or crawl inefficiency.
Can APIs safely return 503 instead of 504?
Only when it matches contract semantics. API clients often branch logic by exact code, so swapping them can break retries, auth handling, or user-facing errors.
Full guides
HTTP 503 Service Unavailable — full guide · HTTP 503 status reference · HTTP 504 Gateway Timeout — full guide · HTTP 504 status reference · All comparisons