504 Gateway Timeout
The server, acting as a gateway or proxy, did not receive a timely response from the upstream server.
Meaning & Description
Common Causes
- Extremely slow database queries locking up the backend server threads.
- The upstream server is overwhelmed with requests and requests are sitting in a queue for too long.
- A proxy timeout setting (e.g., Nginx `proxy_read_timeout`) is configured too low for the expected response time.
- Network connectivity issues causing packets between the proxy and backend to drop silently.
How to fix a 504 error
- Check the proxy logs (Nginx, HAProxy, AWS ALB) to confirm which exact route triggered the timeout.
- Check the application backend logs to see if the request was actually received and if it was still processing when the proxy cut the connection.
- Optimize the slow endpoint. If it involves a heavy database query, add indexes or move the work to an asynchronous background job.
- If the endpoint legitimately takes a long time (like exporting a massive CSV), increase the timeout configuration on your proxy or load balancer.
Browser & SEO Behaviour
Browser Behavior
Displays a standard 504 error page. Browsers do not automatically retry the request.
SEO Impact
Negative if persistent. If Googlebot consistently encounters 504s, it assumes the site is unhealthy, slows down crawl rates, and may de-index the affected pages.
CDN Behavior
CDNs will usually return a styled 504 page. Some CDNs allow configuring the timeout limit before they assume the origin is unresponsive.
Code Examples
HTTP/1.1 504 Gateway Timeout
Content-Type: text/html
<html>
<body>
<h1>504 Gateway Timeout</h1>
<p>The upstream server took too long to respond.</p>
</body>
</html>const httpProxy = require("http-proxy");
// Create a proxy with a 5-second timeout
const proxy = httpProxy.createProxyServer({
proxyTimeout: 5000
});
proxy.on("error", function (err, req, res) {
if (err.code === "ECONNRESET" || err.code === "ETIMEDOUT") {
res.writeHead(504, { "Content-Type": "application/json" });
res.end(JSON.stringify({ error: "Gateway Timeout" }));
} else {
res.writeHead(502);
res.end();
}
});# Adjusting Nginx timeouts to prevent premature 504 errors
server {
location /api/export {
proxy_pass http://backend;
# Wait up to 120 seconds before throwing a 504
proxy_read_timeout 120s;
proxy_connect_timeout 120s;
}
}Raw HTTP Response Example
HTTP/1.1 504 Gateway Timeout
Server: nginx/1.24.0
Content-Type: application/json
{
"error": "Gateway Timeout",
"message": "The upstream server failed to respond in time."
}Real-world Examples
Frequently Asked Questions
How do I fix a 504 Gateway Timeout?
You must speed up the backend process causing the delay (e.g., optimize database queries), or increase the timeout limit configured in your load balancer or proxy server.
What is the difference between a 408 Request Timeout and a 504 Gateway Timeout?
408 means the client (the browser) took too long to send the request data to the server. 504 means a proxy server took too long waiting for an upstream backend server to finish processing the request.
Why do I get a 504 error on Vercel or AWS Lambda?
Serverless platforms have strict execution time limits (often 10-30 seconds). If your function does not return a response before the limit, the platform forcefully terminates the execution and returns a 504 to the user.
Is a 504 error my network’s fault?
Usually no. It is an infrastructure issue on the website’s side. However, in rare cases, a local corporate firewall or proxy taking too long to scan a response can trigger a local 504.
Did You Know?
A 504 error does not necessarily mean the backend server failed. Often, the proxy cuts the connection and returns a 504, but the backend server continues processing the heavy task unaware that the client is gone.
Long-polling and WebSockets require special timeout configurations in proxies like Nginx to avoid dropping idle connections with 504 errors.
Developer Tips
- For tasks that take longer than a few seconds (like generating PDFs or heavy CSVs), use an asynchronous architecture. Return a 202 Accepted immediately, process the job in the background (e.g., using Redis/Celery), and have the client poll for the result.
- Always ensure your load balancer timeout is slightly longer than your application server timeout. If the application times out first, it can log a meaningful error; if the proxy times out first, the application is left blind.
Interview Questions
These are questions you might face in a backend or API design interview that touch on HTTP 504.
Your application logs show successful 200 OK responses, but users report seeing 504 errors on a specific report generation feature. What is happening?
The report generation is taking longer than the proxy/load balancer timeout. The proxy gives up and sends a 504 to the user, but the application server continues processing the report in the background, eventually succeeding and logging a 200 OK, completely unaware the connection was dropped.
How do you redesign an API endpoint that frequently suffers from 504 timeouts?
I would convert it to an asynchronous pattern. The endpoint should validate the request, queue a background job, and immediately return a 202 Accepted with a URL where the client can poll for the job status.
Common Interview Mistakes
- Confusing 504 Gateway Timeout with 408 Request Timeout. They happen at completely different stages of the request lifecycle.
- Assuming that just increasing the proxy timeout to 5 minutes is the best solution. Long-held synchronous HTTP connections consume worker threads and are highly vulnerable to DoS attacks.