Opscraft
HTTP & status codes · Lesson 5 of 9 · 3 min read

5xx server errors and who generates them

The codes

Code Meaning One-line diagnosis
500 Internal Server Error Unhandled error in the application App bug/exception — read app logs and traces
501 Not Implemented Server doesn't support the functionality Unsupported method/feature
502 Bad Gateway A proxy/gateway got an invalid response from upstream, or the upstream closed/reset the connection Upstream crashed, wrong port/protocol, keep-alive race, TLS mismatch to backend
503 Service Unavailable Server can't handle the request right now No healthy targets, overload, maintenance, circuit open; should send Retry-After
504 Gateway Timeout A proxy/gateway didn't get a response in time from upstream Slow upstream, timeouts misaligned, blocked network path to the upstream
505 HTTP version not supported Rare

502 vs 504 in one line: 502 — the upstream answered badly or hung up; 504 — the upstream didn't answer in time.

Enlarge diagram502 Bad Gatewayproxyapp503 ServiceUnavailableproxyapp504 Gateway Timeoutproxyappthe app answered badly or hung upcrash, wrong port, keep-alive raceno healthy app to send tofailing health checks, no ready podsthe app did not answer in timeslow query, hung upstream, blocked path
Figure 1. 502, 503 and 504 all come from a proxy in front of your app. Each describes a different way the app failed it.
Swipe sideways to see all of it, or tap to open it full screen.

Who generated the 5xx?

In a modern request path there are many layers — CloudFront → WAF → ALB → ingress-nginx/Envoy → service mesh sidecar → app. Each can generate its own 5xx. The first diagnostic question is which layer produced it:

Layer How to tell
ALB CloudWatch: HTTPCode_ELB_5XX_Count (LB generated) vs HTTPCode_Target_5XX_Count (target returned it). ALB access logs: elb_status_code vs target_status_code (- = no response from target)
CloudFront x-cache: Error from cloudfront, distinctive HTML error page, CloudFront logs x-edge-result-type
API Gateway x-amzn-ErrorType header, execution logs; integration timeout (29 s default for REST APIs) → 504
ingress-nginx Nginx-styled error page; access log $upstream_status, $upstream_addr, $upstream_response_time; error log "upstream prematurely closed connection", "connect() failed (111: Connection refused)", "upstream timed out (110)"
Envoy / Istio server: envoy, response flags in access logs: UF (upstream connection failure), UH (no healthy upstream), UT (upstream timeout), UC (upstream connection termination), URX (retry limit exceeded), NR (no route)
App App's own error body/format, app logs with the request ID

Response headers (server:, via:, x-cache:) and body formats are fast clues; request IDs and access logs give proof.

Enlarge diagramCloudFrontx-cache: ErrorWAF403 blocksALBELB_5XX metricingress-nginx$upstream_status in logsEnvoy sidecarflags UF, UH, UTyour appits own error body
Figure 2. A request passes many layers, and any of them can return a 5xx. Headers, error pages and per-layer metrics tell you which one did.
Swipe sideways to see all of it, or tap to open it full screen.