504 Gateway Timeout
This is an educational reference page about HTTP 504 Gateway Timeout. The page itself is served as 200 OK so it can be indexed as HTTP documentation.
The server, while acting as a gateway or proxy, did not receive a timely response from an upstream server it needed to complete the request.
Specification
Registered in the IANA HTTP Status Code Registry as Gateway Timeout. Defined in RFC 9110, Section 15.6.5.
What it means
HTTP 504 Gateway Timeout means a gateway or proxy waited for an upstream server and gave up before it answered. The upstream request may still be running, and may still succeed, after the client already received the 504.
When to use it
- A proxy, load balancer, or CDN returns 504 when the upstream server takes longer than its timeout.
- An API gateway can return 504 when a backend call times out.
- Use 502 instead when the upstream answered with something invalid or refused or reset the connection.
Common causes
- Slow database queries or reports that take longer than the proxy timeout.
- An upstream server stuck on its own slow dependency.
- Timeouts set lower at the proxy than in the application. nginx's proxy_read_timeout defaults to 60 seconds.
- Network problems between the proxy and the upstream server.
How to fix it
- Find the slow request in the application logs or traces, and fix the slow query or call.
- Move long work into a background job and return 202 Accepted with a status URL.
- Align timeouts across CDN, load balancer, proxy, and application so the right layer times out with a clear error.
- Raise the proxy timeout only when the work is expected to take that long.
Examples
Slow report behind a proxy
GET /reports/annual?year=2025 HTTP/1.1
Host: app.example.com
HTTP/1.1 504 Gateway Time-out
Server: nginx
Content-Type: text/html
<html><head><title>504 Gateway Time-out</title></head>...Common mistakes
- Assuming the request failed. After a 504, a POST may still complete on the upstream server.
- Retrying a non-idempotent request after a 504 without an idempotency key. The client can create duplicates.
- Raising every timeout to several minutes instead of moving slow work to a background job.
Developer notes
504 leaves the result unknown, not failed. Design writes to be safely retryable, with an idempotency key or a client-generated ID, so clients can retry after a timeout without creating duplicates.
Questions
What does HTTP 504 Gateway Timeout mean?
HTTP 504 means a gateway or proxy did not get a response from the upstream server in time.
Did my request fail if I got a 504?
Not necessarily. The upstream server may still finish the request. Check before retrying a write.
How do I fix 504 Gateway Timeout?
Find out why the upstream is slow and fix that first. Move long work to a background job, and raise proxy timeouts only when the wait is expected.
See also
Header and content rules
RFC 9110 adds no header or content rule specific to 504. The 5xx class rules also apply. See 504 in the response obligations table.