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.
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
GET /api/reports/annual HTTP/1.1 Host: api.example.com 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.