502 Bad Gateway vs 504 Gateway Timeout: Key Differences

Quick Decision

• -Use 502 when a gateway/proxy receives an invalid response from upstream.
• -Use 504 when a gateway/proxy does not receive a timely response from upstream.
• -If the gateway got a bad upstream response, it is 502; if the gateway hit deadline waiting, it is 504.

Key Differences

• -Both statuses are defined for intermediary roles (gateway/proxy), not generic origin execution failures.
• -502 means an upstream response exists but cannot be used as a valid response by the intermediary.
• -504 means the intermediary waited for upstream and timed out before receiving a usable response.
• -502 remediation is contract/protocol correctness; 504 remediation is latency, capacity, or timeout-budget alignment.

Step-by-Step Diagnosis

1. 1Confirm the status is emitted by a gateway/proxy layer (edge, API gateway, reverse proxy).
2. 2Inspect intermediary logs: invalid-upstream-response signatures suggest 502; timeout signatures suggest 504.
3. 3Compare upstream latency distributions against configured intermediary timeout values.
4. 4Validate deadline chain across hops so downstream budgets are stricter than caller budget.

Common Misclassifications

• -Labeling upstream-response validity failures as 504 and only increasing timeouts.
• -Labeling pure upstream slowness/timeouts as 502 and debugging protocol paths first.
• -Returning generic 500 at the gateway and losing the upstream-boundary signal.

Response Examples

HTTP/1.1 502 Bad Gateway
Content-Type: application/json

{
  "error": "bad_gateway",
  "gateway": "edge-gateway-01",
  "upstream": "payments-service",
  "message": "Received invalid response from upstream."
}

HTTP/1.1 504 Gateway Timeout
Content-Type: application/json

{
  "error": "gateway_timeout",
  "gateway": "edge-gateway-01",
  "upstream": "payments-service",
  "message": "Upstream did not respond before timeout budget expired."
}

Pro Tip

Frequently Asked Questions