An HTTP 504 Gateway Timeout response occurs when a server acting as a gateway or proxy does not receive a timely response from an upstream server it needs to complete the request.

HTTP 504 at a glance

  • Status: 504
  • Phrase: Gateway Timeout
  • Class: 5xx Server Error
  • Typical context: A server acting as a gateway or proxy
  • Upstream response: Not received within applicable timeout conditions
  • Client retry: Depends on request semantics and the API contract

What a 504 response tells you

When a client receives a 504 status code, specific protocol facts are established:

  1. The intermediary generated the 504 response: It was able to process the request far enough to return a gateway timeout response.
  2. The timeout occurred at the intermediary: The intermediary stopped waiting for the upstream response under its configured or applicable timeout conditions.
  3. The upstream response was not received within the applicable timeout conditions: The intermediary did not receive a timely response from the upstream server it needed to complete the request.

What a 504 does not tell you

A 504 response identifies where the timeout was observed: at a server acting as a gateway or proxy. By itself, it does not identify the exact cause in the upstream chain.

Client -> Gateway or proxy -> Upstream service

Receiving an HTTP 504 does not prove:

  • The application itself is slow.
  • A database is slow.
  • An external dependency is unavailable.
  • An upstream service is down.
  • A particular timeout setting was used.

Isolating the root cause usually requires observations from the parts of the request path you own, such as logs, metrics, traces, or request timing.

Similar status codes

Several 4xx and 5xx status codes describe related network or timeout conditions. Understanding their distinct protocol roles prevents misdirected debugging:

502 Bad Gateway

The gateway or proxy received an invalid response from upstream.

503 Service Unavailable

The server is not ready to handle the request.

504 Gateway Timeout

The gateway or proxy did not receive a timely response from upstream.

408 Request Timeout

The server did not receive a complete request message from the client within the time it was prepared to wait.

While status 408 concerns the origin server waiting for the client to complete sending its request over an open connection, status 504 concerns an intermediary proxy waiting for an upstream server to return its response. Neither status is automatically safe to retry without verifying request idempotency and server semantics.

For detailed side-by-side protocol comparisons, see our dedicated guides on 502 vs 504 and 408 vs 504, or our reference on 502 Bad Gateway and 503 Service Unavailable.

Diagnostic scenarios

Two common situations illustrate how a 504 can arise in practice:

Scenario 1: Long-running processing exceeds gateway deadline

An API endpoint performs a complex calculation, report generation, or multi-table database aggregation. The upstream application accepts the request and begins working normally. However, because the processing duration exceeds the gateway’s applicable timeout conditions, the gateway returns a 504 response to the client. Depending on the system, the upstream work may continue, be cancelled, or fail independently.

Scenario 2: Upstream dependency delay or connectivity stall

An upstream application synchronously calls an external service or secondary microservice during request handling. If that dependency hangs or experiences network latency without failing immediately, the delay bubbles up the request path until the intermediary gateway’s waiting window expires.

Common causes of HTTP 504

Slow upstream processing

Long-running work in an upstream service can contribute to a delayed response in systems where it occurs.

Delayed dependency response

An upstream service may be waiting on another service or dependency before it can complete its response.

Request-path delay

Queueing, connectivity issues, or policy differences across owned services can affect how long an intermediary waits.

Headers you may encounter

HTTP 504 does not require a fixed set of response headers. The headers present depend on the server, gateway, proxy, and application:

  • Content-Type: Describes a response representation when a response body exists.
  • Date: Indicates when the HTTP message originated.
  • Via: Can provide information about intermediaries that handled a message.
  • Retry-After: May appear in some server policies, but is not a required or typical HTTP 504 response header.

Troubleshooting flow

When troubleshooting an HTTP 504 error, follow a structured diagnostic path:

HTTP 504
  |
  +-- Is the failure consistent?
        |
        +-- Yes: Compare endpoint behavior and owned service logs.
        |
        +-- No: Compare traffic conditions, dependency behavior, and
            request timing.

The next investigation step depends on which parts of the request path you own and can observe.

What to check before changing code

Before changing application code or timeout policies, first identify which part of the request path you own and can observe.

  1. Determine whether the failure is isolated to one endpoint or affects multiple routes.
  2. Compare the timing of the client request, intermediary response, and owned upstream service where available.
  3. Check whether a dependency was involved in the affected request.
  4. Look for a pattern involving traffic level, request size, or long-running operations.
  5. Confirm whether the request may have completed upstream even though the client received no successful response.

How to verify the fix

Measure endpoint latency and inspect proxy behavior using curl:

curl -i -w "Time total: %{time_total}s\n" \
  https://api.example.test/v1/reports/export

Observed request duration can be a useful clue, but it does not prove the configured timeout value of a gateway or proxy. Confirm the actual request path and server-side behavior using systems you own.

Review application logs, query execution times, and upstream service response durations across owned systems to isolate the source of the delay before making code or configuration changes.

Remediation paths to evaluate

If an owned upstream service is slow

Measure where time is spent before changing limits or capacity.

If a dependency response is delayed

Review the dependency contract, failure handling, and request behavior within systems you own.

If the operation is inherently long-running

Consider whether asynchronous processing is appropriate for the API design and client expectations.

If timeout policies differ across owned services

Compare the request path before changing any timeout value.

Select a remediation path only after identifying the part of the request path that can be observed and changed safely.

FAQ

Is HTTP 504 the same as HTTP 502?

No. While both status codes describe intermediary gateway conditions, status 504 indicates that the gateway or proxy did not receive a timely response from upstream, whereas status 502 indicates that the gateway or proxy received an invalid response from upstream.

Does HTTP 504 prove that the upstream application is slow?

No. An HTTP 504 confirms only that the gateway gave up waiting before receiving an upstream answer. The delay could stem from network transit latency between proxy and upstream, connection queuing, or a slow external dependency.

Can a client safely retry after HTTP 504?

Not automatically. Because a 504 indicates a timeout, the upstream server may still have received and executed the request even though the client never received the response. Retry safety depends on request semantics, idempotency, and the API contract.

Key takeaway

HTTP 504 Gateway Timeout indicates that an intermediary server acting as a gateway or proxy did not receive a timely response from an upstream server. Rather than assuming a specific component is at fault or changing timeout values prematurely, isolate which part of the request path can be observed and verified across the systems you own.