504 - Gateway Timeout
HTTP 504 Gateway Timeout means a gateway or proxy did not receive a timely response from an upstream server.
Last reviewed: February 12, 2026|Editorial standard: source-backed technical guidance
What Does Gateway Timeout Mean?
The gateway waited for an upstream response longer than its deadline, so requests time out at the proxy boundary before completion.
Common Causes
- -Upstream latency exceeds gateway timeout settings.
- -Backend queueing delays increase under load.
- -Timeout values are inconsistent across service hops.
How to Fix Gateway Timeout
- 1Identify the slow upstream hop and reduce tail latency (query optimization, pool tuning, dependency fan-out reduction).
- 2Align timeout ladder across client, gateway, and upstream so deadlines are monotonic and intentional.
- 3Move long-running operations to async workflows instead of blocking gateway request deadlines.
Step-by-Step Diagnosis for Gateway Timeout
- 1Capture end-to-end trace timings and isolate which upstream span exceeds gateway timeout.
- 2Compare timeout settings across all hops and detect cases where intermediary deadlines are shorter than upstream work.
- 3Inspect queueing, thread pool wait, and connection pool contention on slow upstream services.
- 4Retest with controlled load and adjusted timeout budgets to confirm timeout source is removed.
Timeout Ladder and Deadline Propagation Audit
- -Verify monotonic timeout chain (example: gateway 30s timeout while upstream endpoint regularly needs 45s).
- -Check deadline propagation headers/context (example: upstream ignores client deadline and runs until proxy timeout fires).
Upstream Latency and Queue Contention Analysis
- -Inspect high-percentile latency contributors (example: database query regression pushes p99 beyond gateway timeout).
- -Trace resource contention effects (example: connection pool starvation causes long wait before request execution starts).
Implementation Examples
curl -i -X GET https://api.example.com/v1/resource
# Response:
# HTTP/1.1 504 Gateway Timeout
# {"error":"Gateway Timeout","code":"504"}const response = await fetch('https://api.example.com/v1/resource', {
method: 'GET',
headers: { 'Accept': 'application/json' }
});
if (response.status === 504) {
console.error('Handle 504 Gateway Timeout');
}import requests
response = requests.get(
'https://api.example.com/v1/resource',
headers={'Accept': 'application/json'}
)
if response.status_code == 504:
print('Handle 504 Gateway Timeout')How to Verify the Fix
- -Re-run affected flows and confirm upstream responses complete before gateway deadlines.
- -Validate timeout and retry behavior under both nominal and burst traffic conditions.
- -Monitor p95/p99 latency plus 504 rate to ensure sustained recovery over time.
How to Prevent Recurrence
- -Standardize timeout budgets and retry policies across all service boundaries.
- -Continuously probe DNS, TLS, and upstream health paths with synthetic checks.
- -Implement graceful degradation and circuit-breaking for upstream latency spikes.
Pro Tip
- -enforce timeout-budget contracts in CI so gateway and service deadlines cannot drift apart across config repositories.
Decision Support
Compare Guide
502 Bad Gateway vs 504 Gateway Timeout: Key Differences
Fix upstream errors faster: use 502 when a gateway gets an invalid upstream response, and 504 when the upstream service exceeds your timeout budget.
Compare Guide
429 Too Many Requests vs 503 Service Unavailable
Use 429 for caller-specific throttling and 503 for service-wide outages, so retry behavior, escalation paths, and incident ownership stay correct.
Playbook
API Timeout Playbook (502 / 504 / DEADLINE_EXCEEDED)
Use this playbook to separate invalid upstream responses from upstream wait expiration and deadline exhaustion, and apply timeout budgets, safe retries, and circuit-breaker controls safely.
Playbook
Availability and Dependency Playbook (500 / 503 / ServiceUnavailable)
Use this playbook to separate origin-side 500 failures from temporary 503 dependency or capacity outages, then apply safe retry and escalation paths.
Official References
Provider Context
This guidance is specific to HTTP services. Always validate implementation details against official provider documentation before deploying to production.