HTTP 504 Gateway Timeout – What It Means and How to Fix It
Learn what HTTP 504 Gateway Timeout means, which hop timed out, how to tell it apart from 502 and 503, and how to fix slow upstreams.
A 504 comes from an intermediary — a proxy, load balancer, or CDN — that waited for an upstream response and gave up. Something behind the edge was too slow, not absent.
1. What Does HTTP 504 Mean?
A gateway timed out waiting for the server it forwards to.
- The request reached the edge. Connectivity to the site is fine.
- The upstream was reachable but slow. That is the difference from 502.
- A timer expired. The value belongs to the intermediary, not to your client.
2. Common Causes
- A slow query or operation on the origin exceeding the proxy's limit.
- Upstream saturation — every worker busy, so the request queues past the deadline.
- A blocking dependency the origin is itself waiting on.
- A timeout mismatch, where the proxy's limit is shorter than the origin's own.
- Genuinely long work performed synchronously in a request.
- Network path problems between edge and origin.
3. How to Diagnose It
Time the request and note whether it fails at a consistent duration — a repeatable 30 or 60 second failure points directly at a configured limit.
Then determine which hop owns that limit. Requesting the origin directly, bypassing the edge, is the fastest way to separate "the origin is slow" from "the edge is impatient".
4. How to Fix It as a Client
| Situation | Action |
|---|---|
| Occasional under load | Retry later with wider spacing; reduce concurrency |
| One specific endpoint | Narrow the request — fewer fields, smaller page size, tighter filters |
| Consistent at a fixed duration | The limit is server-side; the client cannot change it |
| Long-running operation | Look for an asynchronous variant that accepts and polls |
5. How to Fix It as an Operator
- Profile the slow path — the answer is usually one query or one external call.
- Align timeouts so the origin's limit is shorter than the gateway's, producing a clear error instead of a timeout.
- Move long work out of the request into a job with a polling endpoint.
- Add caching for expensive, repeatable responses.
- Check connection pool sizes; exhaustion looks exactly like slowness.
6. HTTP 504 Versus Related Codes
- 502 — the upstream answered with something invalid or refused the connection.
- 503 — no upstream was available to try.
- 504 — an upstream was tried and did not answer in time.
- 408 — the client was too slow sending its request, the mirror image of 504.
7. Real-World Examples
- A report endpoint that scans a large table and exceeds a 60-second edge limit.
- A checkout call blocked on a slow payment provider.
- A cold serverless function whose start plus work crosses the gateway deadline.
- An origin under load where queueing, not processing, consumes the budget.
8. Summary
HTTP 504 means an intermediary stopped waiting for an upstream that was reachable but slow. The failing duration usually identifies which configured limit expired.
Clients can narrow the request and reduce concurrency; operators fix the slow path, align timeouts so failures are explicit, and move genuinely long work into asynchronous jobs.