When you see this status
- Upstream service is unresponsive or overloaded
- Network partition between gateway and backend
- Backend service crashed or hung
- Misconfigured proxy timeout settings
- DNS resolution failure for upstream host
Common causes
- Backend service latency exceeding gateway timeout
- Network congestion or routing issues
- Backend service outage or crash
- Proxy timeout configuration too low
- Upstream service not responding to keep-alives
How to debug it
- Check upstream service health and logs
- Increase proxy timeout settings if appropriate
- Verify network connectivity to upstream host
- Inspect backend service performance metrics
- Review proxy/gateway configuration for errors
Return this code in your framework
Express (Node.js)
res.status(504).send('Gateway Timeout');
FastAPI (Python)
from fastapi import HTTPException
raise HTTPException(status_code=504, detail="Gateway Timeout")
NestJS
@Get()
getData() {
throw new HttpException('Gateway Timeout', HttpStatus.GATEWAY_TIMEOUT);
}
Go (net/http)
w.WriteHeader(http.StatusGatewayTimeout)
w.Write([]byte("Gateway Timeout"))
About HTTP 504
HTTP status code 504 Gateway Timeout is part of the
5xx Server Error family. The server acting as a gateway or proxy did not receive a timely response from an upstream server. Understanding it is essential for
backend engineers, API designers, and anyone debugging integrations between services.
The Qaynaq Labs HTTP Status Code Explainer covers all standard codes with practical guidance:
what triggers them, how to debug them in production, and exactly how to return them from common
frameworks. Each code page is hand-curated and verified.