HTTP 504 Gateway Timeout Error: Causes and How to Fix It

The 504 Gateway Timeout error occurs when a gateway or proxy does not receive a response from the origin server within the specified time. It differs from 502: in 504, the intermediary waited but did not receive an HTTP response in time. The investigation should follow the request from outside to inside.

Direct Response: How to Fix 504

Log the time, route, and request ID; confirm which proxy responded; test the origin directly; compare timeouts; examine application duration, database queries, and external calls. Fix the slow work or turn it into an asynchronous task. Increasing the timeout is a temporary measure when the long duration is legitimate and controlled.

Step 1: Map the Request Path

browser -> CDN/WAF -> load balancer -> Nginx -> application -> database/external API

Each arrow may have its own limit. A CDN may give up before Nginx; Nginx may give up before the application; the application may wait for a query without a timeout. Discover who generated the error page through the headers and the vendor's dashboard.

Step 2: Reproduce with Identification

curl -v --max-time 70 \
  -H "X-Request-ID: diagnostico-504-001" \
  https://exemplo.com/relatorio

Test the same route directly at the origin only in an authorized environment. If the origin also takes time, the problem lies with it or below it. If the origin is fast, examine the proxy, DNS, connection, and intermediary capacity.

Step 3: Correlate Logs

Look for the request ID across all layers. Log the start, end, and duration of each dependency. Useful metrics include p50, p95, and p99, active connections, CPU saturation, memory, queue, database pool, and slow queries.

Step 4: Address Database and Dependencies

Use EXPLAIN (ANALYZE, BUFFERS) on a safe copy or controlled query. Do not perform destructive analysis in production. Check filters, indexes, returned volume, and N+1. For external services, set timeouts shorter than the total deadline and retries only for idempotent operations, with exponential backoff and randomness.

Step 5: Offload Long Tasks from the Request

Exporting, importing, image processing, and extensive reporting do not need to keep an HTTP connection open. The API can create a job, respond with 202 Accepted, process in a queue, and make the result available later. Ensure idempotency to avoid duplication when the client retries.

Nginx Configuration with Caution

location /api/ {
  proxy_connect_timeout 5s;
  proxy_send_timeout 30s;
  proxy_read_timeout 30s;
  proxy_pass http://aplicacao;
}

The values are examples, not universal recommendations. proxy_read_timeout measures the interval between reads, not the total operation time. Before increasing it, estimate the impact of stuck connections and capacity.

How to Prevent New 504s

• SLO for critical journey;
• explicit timeout on all external calls;
• latency dashboard by route and dependency;
• alert before saturation;
• load testing with realistic scenarios;
• queues with limits, retries, and dead-letter;
• health endpoint that does not depend on everything;
• runbook with responsible parties and rollback.

Also read error 502 in Nginx, error 500 in API, and the guide on API monitoring.

Frequently Asked Questions

Does restarting the server resolve it?

It may temporarily free a resource, but it does not explain the cause. Preserve metrics and logs before restarting when the operation allows.

Is increasing the timeout safe?

Only when the duration is expected and capacity has been calculated. Otherwise, the system accumulates work and fails later.

Primary Sources

• MDN: status 504 Gateway Timeout
• Nginx: proxy_read_timeout
• RFC 9110: status 504