Skip to content

504 Gateway Timeout

A gateway or proxy did not receive a timely response from the upstream server it needed to complete the request.

Status

HTTP/1.1 504 Gateway Timeout

Details

  • Category: 5xx
  • Status: Standard. Registered with IANA and defined by a current standards-track RFC.
  • Specification: RFC 9110 §15.6.5
  • Cacheable: Only with explicit cache headers
  • Response body: Allowed
  • Retry: Retry after a delay

504 means the upstream was reachable but too slow. The intermediary waited out its configured timeout and gave up. Unlike 502, a connection was established: the work simply did not finish in time.

It usually points at one slow dependency rather than a broken service. A single unindexed query, a blocking external API call, or a lock contention hotspot will produce 504s under load while everything else looks healthy.

Note: A 504 does not tell you whether the work completed upstream. Retry only requests that are safe to repeat.

Common causes

  • A backend request exceeded the proxy's read timeout.
  • A slow database query, often one that only becomes slow as data grows.
  • A synchronous call to a third-party API that is itself degraded.
  • Thread or connection pool exhaustion leaving requests queued behind slow work.
  • A proxy timeout set lower than the application's own timeout, so the proxy gives up first.

How to fix it

As the client

  • Retry with backoff, but only for idempotent requests. A 504 does not tell you whether the work completed upstream.
  • Break large operations into smaller ones that finish well inside the timeout.
  • Use an asynchronous endpoint if the API offers one, so long work is not held on a connection.

As the server

  • Find the slow dependency with tracing rather than raising the timeout, which only moves the symptom.
  • Align timeouts across the stack so the innermost layer fails first with a meaningful error.
  • Move genuinely long operations to a job queue and return 202 with a status URL.

Examples

A backend that ran past the proxy timeout

A request for a report that takes longer than the proxy will wait:

HTTP request

GET /api/reports/annual HTTP/1.1
Host: api.example.com

The upstream was reachable but too slow, which is what separates 504 from 502:

HTTP response

HTTP/1.1 504 Gateway Timeout
Content-Type: text/html; charset=utf-8
Server: nginx

Notes for proxy users

Timeouts through a proxy stack on top of each other: your client timeout, the proxy's, and the target's. When you see 504s in automation, compare the same request made directly. If both are slow, the target is the bottleneck and raising your own timeout is the only useful change.

Specifications

See also