502 - Bad Gateway
HTTP 502 Bad Gateway means a gateway or proxy received an invalid response from an upstream server.
Last reviewed: February 12, 2026|Editorial standard: source-backed technical guidance
What Does Bad Gateway Mean?
The gateway reached an upstream target but could not use its response, so client traffic fails at the edge until upstream response integrity is restored.
Common Causes
- -Upstream closed connection before returning valid response.
- -Gateway cannot parse upstream headers or protocol framing.
- -TLS handshake or certificate chain fails between hops.
How to Fix Bad Gateway
- 1Identify which upstream pool/member is emitting invalid responses and drain unhealthy targets immediately.
- 2Validate upstream protocol correctness (status line, headers, framing) and TLS chain compatibility with gateway expectations.
- 3Retest through the same edge path after fixing upstream response integrity and connection settings.
Step-by-Step Diagnosis for Bad Gateway
- 1Capture gateway error logs with upstream endpoint, connection ID, and parse failure reason for 502 events.
- 2Compare successful versus failing upstream responses at raw header/framing level.
- 3Inspect TLS handshake, SNI, and certificate trust between gateway and upstream services.
- 4Retest with canary upstream routing to confirm failure is isolated to specific upstream instances or config paths.
Upstream Response Integrity Inspection
- -Inspect malformed upstream payload framing (example: invalid chunk termination or truncated header block causes proxy parse failure).
- -Verify upstream status/header semantics are RFC-compliant (example: illegal header bytes returned after recent reverse-proxy upgrade).
Gateway-to-Upstream Connectivity and TLS Audit
- -Trace TLS negotiation details and trust store alignment (example: rotated intermediate cert not trusted by edge gateway nodes).
- -Validate routing/service discovery correctness (example: gateway resolves to deprecated upstream port speaking wrong protocol).
Implementation Examples
curl -i -X GET https://api.example.com/v1/resource
# Response:
# HTTP/1.1 502 Bad Gateway
# {"error":"Bad Gateway","code":"502"}const response = await fetch('https://api.example.com/v1/resource', {
method: 'GET',
headers: { 'Accept': 'application/json' }
});
if (response.status === 502) {
console.error('Handle 502 Bad Gateway');
}import requests
response = requests.get(
'https://api.example.com/v1/resource',
headers={'Accept': 'application/json'}
)
if response.status_code == 502:
print('Handle 502 Bad Gateway')How to Verify the Fix
- -Re-run failing requests and confirm gateway receives parseable, valid upstream responses.
- -Validate error rate by upstream target remains stable during normal and peak traffic.
- -Confirm synthetic gateway probes to each upstream node stay green over sustained intervals.
How to Prevent Recurrence
- -Gate upstream deployments with protocol-conformance tests and edge compatibility checks.
- -Continuously probe DNS, TLS, and upstream health paths with synthetic checks.
- -Use outlier detection and automatic ejection for upstream nodes returning invalid responses.
Pro Tip
- -record sampled raw upstream response headers at the gateway for 502s so parser failures can be diagnosed without reproducing live incidents.
Decision Support
Compare Guide
500 Internal Server Error vs 502 Bad Gateway: Root Cause
Debug 500 vs 502 faster: use 500 for origin failures and 502 for invalid upstream responses at gateways, then route incidents to the right team.
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.
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.