>_ NetDevKit
5xx Server & Gateway Error

HTTP 502 Bad Gateway — Reverse Proxy & Gateway Troubleshooting

HTTP 502 Bad Gateway occurs when an edge gateway or reverse proxy (Nginx, Caddy, Envoy, AWS ALB, Cloudflare) receives an invalid TCP reset (RST), premature EOF, or refused connection (ECONNREFUSED) from its upstream backend.

Status Code502 Bad Gateway
Specification / OriginRFC 9110 §15.6.3
Failure LayerReverse Proxy -> Upstream Socket
Retry SafetySafe for idempotent GET/HEAD with exponential backoff + jitter

Interactive HTTP 502 Live Probe & Log Command Builder

Enter your target endpoint below to generate copy-ready curl latency breakdown probes and origin bypass tests:


  

    Related diagnostics:
    Nginx & Caddy Proxy Generator → ·
    X.509 SSL Certificate Decoder → ·
    Offline JWT Expiry Inspector →
  






  
Production Root Causes & Remediation Guide

  
Top production culprits: (1) upstream Node/Python/Go container OOM-killed or listening on 127.0.0.1 instead of 0.0.0.0, (2) upstream keep-alive idle timeout shorter than the load balancer's idle timeout causing race-condition TCP resets, or (3) oversized response headers overflowing proxy_buffer_size.

  
Step-by-Step Engineering Fix

  
Verify upstream socket reachability (ss -tlnp), set backend keep-alive timeout HIGHER than AWS ALB/Nginx upstream keepalive (e.g., 65s on app vs 60s on ALB), and raise proxy_buffer_size 16k if large Set-Cookie headers trigger 'upstream sent too big header'.

  
Recommended Nginx / Reverse-Proxy Configuration Snippet

  
proxy_http_version 1.1;
proxy_buffer_size 16k;
proxy_buffers 4 32k;
proxy_busy_buffers_size 32k;







  
Frequently Asked Questions (HTTP 502)

  
  

    Why do intermittent 502 Bad Gateway errors happen on AWS ALB under light traffic?
    
If Node.js keepAliveTimeout (default 5s) is shorter than AWS ALB's idle timeout (default 60s), the backend closes idle sockets right as ALB reuses them, causing sporadic 502s.

  

  
  

    Which infrastructure layer generates HTTP 502 Bad Gateway?
    
HTTP 502 (RFC 9110 §15.6.3) typically originates at the Reverse Proxy -> Upstream Socket layer. HTTP 502 Bad Gateway occurs when an edge gateway or reverse proxy (Nginx, Caddy, Envoy, AWS ALB, Cloudflare) receives an invalid TCP reset (RST), premature EOF, or refused connection (ECONNREFUSED) from its upstream backend.

  

  
  

    Should API clients automatically retry HTTP 502 responses?
    
HTTP 502 is safe to retry ONLY for idempotent methods (such as GET or HEAD) using exponential backoff with random jitter.

  

  






  
Browse All 25 Gateway, Proxy & Cloud HTTP Error Guides

  

    
      HTTP 400 (Bad Request)
    
      HTTP 401 (Unauthorized)
    
      HTTP 403 (Forbidden)
    
      HTTP 404 (Not Found)
    
      HTTP 405 (Method Not Allowed)
    
      HTTP 408 (Request Timeout)
    
      HTTP 413 (Content Too Large)
    
      HTTP 422 (Unprocessable Content)
    
      HTTP 429 (Too Many Requests)
    
      HTTP 431 (Request Header Fields Too Large)
    
      HTTP 499 (Client Closed Request)
    
      HTTP 500 (Internal Server Error)
    
      HTTP 501 (Not Implemented)
    
      HTTP 502 (Bad Gateway)
    
      HTTP 503 (Service Unavailable)
    
      HTTP 504 (Gateway Timeout)
    
      HTTP 507 (Insufficient Storage)
    
      HTTP 511 (Network Authentication Required)
    
      HTTP 520 (Web Server Returned an Unknown Error)
    
      HTTP 521 (Web Server Is Down)
    
      HTTP 522 (Connection Timed Out)
    
      HTTP 523 (Origin Is Unreachable)
    
      HTTP 524 (A Timeout Occurred)
    
      HTTP 525 (SSL Handshake Failed)
    
      HTTP 526 (Invalid SSL Certificate)
    
  






  


  
Copied to clipboard