HTTP Status 502 - Bad Gateway

Der HTTP-Status-Code 502 Bad Gateway signalisiert, dass Gateway oder Proxy eine invalide Response vom Upstream-Server erhalten hat. Intermediär konnte Request nicht erfüllen wegen fehlerhafter Communication mit Backend. Typisch bei Backend-Connection-Failures oder Protocol-Errors.

Typ

Response-Status-Code

Syntax

Der Status Code wird von Gateway/Proxy zurückgegeben bei Upstream-Problemen.

http 
HTTP/1.1 502 Bad Gateway

Direktiven

Der 502 Bad Gateway Status Code wird für Upstream-Response-Probleme verwendet.

Invalid Upstream Response
Gateway erhielt Response von Upstream, die nicht valid HTTP ist (malformed Headers, Protocol-Violations, incomplete Response).
Connection Failures
Auch wenn Gateway keine Connection zu Upstream herstellen kann (Connection Refused, DNS-Failure, Network-Error).
Retry Logic
Client sollte Request wiederholen, da 502 oft transient ist (temporäre Backend-Probleme). Load Balancer können zu healthy Backend-Instance failovern.

Beispiele

Nachfolgend finden Sie praktische Anwendungsbeispiele für Status 502.

Beispiel 1 Backend Service Down

http 
GET /api/data HTTP/1.1
Host: api.example.com

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

{
  "error": "bad_gateway",
  "message": "Unable to reach backend service",
  "upstream": "backend-service.internal:8080",
  "error_detail": "Connection refused"
}

Beispiel 2 Invalid Backend Response

http 
POST /api/orders HTTP/1.1
Host: api.example.com
Content-Type: application/json

{"product_id": 42}

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

{
  "error": "invalid_upstream_response",
  "message": "Backend returned malformed response",
  "request_id": "req-xyz-789"
}

Beispiel 3 DNS Resolution Failure

http 
GET /api/external HTTP/1.1
Host: gateway.example.com

HTTP/1.1 502 Bad Gateway
Content-Type: text/html

<html>
<body>
  <h1>Bad Gateway</h1>
  <p>Unable to resolve upstream service hostname</p>
</body>
</html>

Bad Gateway Flow

502 Bad Gateway bei Backend Connection Failure

Vorteile für die Systemarchitektur

  • Clear Layer Separation: 502 signalisiert explizit, dass Fehler in Upstream liegt, nicht im Gateway. Hilft bei Debugging und Incident-Response.
  • Retry-Friendly: Client weiß, dass Gateway funktioniert aber Backend problematisch ist. Kann Retry mit Backoff implementieren oder zu anderem Endpoint failovern.
  • Monitoring Integration: Operations kann 502-Errors nutzen um Backend-Health zu überwachen. Automatic Health-Checks und Failover können getriggert werden.

Spezifikation

RFC 9110, Section 15.6.3 – HTTP Semantics https://www.rfc-editor.org/rfc/rfc9110.html#name-502-bad-gateway

Weitere Spezifikationen

HTTP Status 500 - Internal Server Error, HTTP Status 504 - Gateway Timeout, Via Header