HTTP 504 Gateway Timeout
HTTP 504 Gateway Timeout is the "waited too long for an answer" error. Your proxy (Nginx, Cloudflare, API Gateway) sent a request to the upstream server and sat there waiting — but the upstream took too long and the proxy gave up. The upstream was reachable but too slow.
The key operational distinction from 502: a 502 means the upstream responded quickly but with something invalid. A 504 means the upstream never responded within the timeout window. Both show up as user-facing errors, but the diagnosis is different — 502 is about what came back, 504 is about nothing coming back.
Common production pattern: a database query that runs fine under light load suddenly starts timing out at scale, causing 504s at the gateway level. The fix involves: finding the slow query (database slow query log), optimizing it or adding an index, and potentially increasing the gateway timeout as a temporary measure while the fix ships.
Quick reference
| Code | 504 |
|---|---|
| Name | Gateway Timeout |
| Category | 5xx server errors |
| Specification | RFC 9110 |
| IANA status | Assigned |
| When to use | Gateways and proxies emit 504 automatically. As an application developer, tune upstream timeout configurations and optimize slow processing paths to avoid 504s. Always implement request timeouts on all outbound HTTP calls. |
| Client behavior | May retry — the upstream may be temporarily slow. Implement bounded retry with exponential backoff. After repeated 504s, surface the error and alert. |
| Caching | Not cached. |
Common causes
- Application server processing a slow or expensive operation
- Database query timeout
- External API call hung without responding
- Origin server overloaded under high traffic
How to fix it
- Optimize slow database queries or API calls
- Increase origin timeout if the operation is legitimately long-running
- Add query timeouts and circuit breakers in the application
- Scale the origin horizontally to handle load
Example exchange
GET /example HTTP/1.1 Host: errorlookup.com HTTP/1.1 504 Gateway Timeout
When you see this in production
504 triage:
1. Check application server logs for slow requests — look for requests that match the gateway timeout duration
2. Check database slow query logs
3. Check external API response times
4. Verify Nginx/ALB upstream timeout configuration (proxy_read_timeout in Nginx)
5. Check Cloudflare error 524 logs if using Cloudflare in front of your origin
6. Look for correlation with load spikes — is the 504 rate proportional to traffic?
What developers usually do next
- Debugging 504:
- 1. Reproduce by sending the slow request directly to the upstream (bypassing the proxy) and measuring response time
- 2. Enable slow query logging in your database and correlate query timing with request timing
- 3. Add request-level timing instrumentation to identify which part of your code path is slow
- 4. Tune database query performance (add indexes, optimize N+1 queries)
- 5. Add timeouts to all outbound HTTP calls in your code (a call without a timeout is a 504 waiting to happen)
- 6. If the operation is legitimately long-running, either increase the proxy timeout or move the work to an async queue
When NOT to use this code
Do not confuse 504 with 502 (upstream bad response) or 503 (server deliberately unavailable). Do not increase gateway timeouts as a long-term solution — find and fix the slow upstream operation. Do not return 504 from application code — it is a gateway response.
Related status codes
HTTP 502 Bad Gateway · HTTP 503 Service Unavailable · HTTP 408 Request Timeout
Behind Cloudflare or Nginx?
When a proxy layer detects the same timeout condition, it surfaces as a vendor-specific code. If your users are behind Cloudflare:
Comparisons
HTTP 504 vs 408 · HTTP 504 vs 500 · HTTP 504 vs 502 · HTTP 504 vs 503
Frequently asked questions
What is the difference between 502 and 504?
502 Bad Gateway means upstream returned a bad response. 504 means upstream returned no response within the allowed time. Both point to upstream issues, but the root cause differs.
Standards reference
This definition is derived from the IANA HTTP Status Code Registry and RFC 9110. Human-readable operational guidance by ErrorLookup. · HTTP 504 quick reference →