HTTP 504 Gateway Timeout – Free, Online, Private

What HTTP 504 means

504 says the gateway did not receive a timely response from the upstream. The origin may still be working. That is the dangerous part: the client sees a failure while the server may commit the write a second later. Idempotency matters more here than on a clean 4xx. 504 is not 408. 408 is the server waiting for the client.

504 Gateway Timeout belongs to the 5xx server error class. Clients that only look at the class will group it with its neighbors. Clients that care about the exact code should use the narrower rule on this page, because the class is only the first digit.

When you see HTTP 504

When you see HTTP 504 Gateway Timeout, stop on that exact status line. 504 Gateway Timeout means a proxy timed out waiting for the upstream. The trace that usually produces it: The upstream was alive and slower than the gateway's read timeout. The 5xx server error class only tells you the first digit. A neighbor in that class is a different fault, and the fix on this page does not transfer to it.

Return 504 when you are a gateway and the upstream exceeded your timeout. Set the timeout high enough for legitimate work and low enough that clients are not stuck. Use 408 only when you were waiting for the client. Use 500 if you are the origin and your own code was slow. Do not let an origin return 504 unless it is itself a gateway.

How to fix HTTP 504

To fix HTTP 504, change the condition that made the server choose Gateway Timeout. Retry idempotent requests with backoff. Treat POST as ambiguous unless you have an idempotency key. Do not assume the operation failed. Check before you repeat a payment or a send. Safe methods, yes, with backoff. Unsafe methods, only if the operation is idempotent or you have checked the outcome. If the log line is a different code, leave this page. The mix-up people make with 504 is this one: 408 is a client that did not finish sending. 502 is an invalid upstream response. 500 is the origin crashing. 504 is a wait for the upstream that expired.

• A write committed after the gateway gave up, and the client's retry duplicated it.
• A DNS or connect timeout was reported as 504 and looked like an application bug.
• Increasing the client timeout did nothing because the gateway's timeout was shorter.

An access log that only stores 504 is not enough to tell these apart. Keep the method, the path, and a request id. Do not keep the Authorization header or a request body that might be a token. The status explains the outcome. It is not a place to echo secrets back to the client either.

Example response

HTTP 504 Gateway TimeoutHTTP/1.1 504 Gateway Timeout
Content-Type: text/plain

Gateway timeout

The body is from the gateway. The origin log may show the request still running. If you retry a POST, you may run it twice. An idempotency key makes the second attempt return the first result. Lengthening only the client timeout will not help if the gateway is the component that gave up.

What the client should do

Retry idempotent requests with backoff. Treat POST as ambiguous unless you have an idempotency key. Do not assume the operation failed. Check before you repeat a payment or a send.

Do not cache 504 as the resource. The next attempt may succeed.

Safe methods, yes, with backoff. Unsafe methods, only if the operation is idempotent or you have checked the outcome.

Codes people confuse with HTTP 504

408 is a client that did not finish sending. 502 is an invalid upstream response. 500 is the origin crashing. 504 is a wait for the upstream that expired.