504 Gateway Timeout
The proxy reached the upstream, the upstream accepted the request — and then took longer than the proxy was willing to wait. The application is alive but too slow: a query without an index, a hanging third-party call, an exhausted worker pool.
What usually causes it
- Slow database queries under load
- Downstream API calls without timeouts, hanging the request
- Worker/connection pool exhaustion queuing requests past the deadline
- Proxy timeout set lower than the endpoint's legitimate duration
How to debug and fix it
- Compare the endpoint's real latency distribution against the proxy timeout — one of them is wrong; decide which.
- Add timeouts to every outbound call inside the request path; a request should fail fast, not inherit its slowest dependency.
- Move legitimately-long work to async jobs (return 202 + status URL) instead of raising gateway timeouts.
- Under load, look for pool exhaustion: requests spend the timeout queued, not executing.
Easily confused with
Debugging an API? Build and inspect requests, check response headers, or read the full status-code debugging guide.