HTTP 503 vs 504

Service Unavailable vs Gateway Timeout

Quick Decision

Choose HTTP 503 when the server is temporarily unavailable (overload, maintenance, rate limiting). Choose HTTP 504 when acting as a gateway and upstream times out.

Decision Boundary

HTTP 503 and 504 both signal server failures, but they differ in context and attribution. 503 (Service Unavailable) indicates the server itself is temporarily unable to handle requests (overloaded, maintenance, rate limiting). 504 (Gateway Timeout) is used when acting as a gateway/proxy and the upstream server doesn't respond in time. The boundary lies in whether it's a direct server issue (503) or a gateway timing out waiting for upstream (504).

Decision Logic

Use HTTP 503 for temporary server unavailability; choose HTTP 504 for gateway timeouts.

If: Server is temporarily overloaded, in maintenance, or rate limiting requests

Then: Return HTTP 503 with Retry-After header

503 (Service Unavailable) signals temporary unavailability, telling clients when to retry.

If: Acting as gateway/proxy and upstream server doesn't respond in time

Then: Return HTTP 504

504 (Gateway Timeout) indicates the gateway role and that upstream timed out.

If: Application dependency (database, cache) is unavailable

Then: Return HTTP 503

From the client's perspective, the service is unavailable due to dependency issues.