Server Errors

## Why the class matters before the code HTTP status codes are grouped by their first digit. The 5xx class means the server is aware it has erred or is incapable of performing the request; the request itself is presumed well-formed. That is the fundamental split from the 4xx class, where the client sent something wrong. The practical consequence: a 4xx normally means "do not send that again unchanged", while a 5xx often means "the same request might succeed later". Within 5xx, the individual code is a blame assignment — it tells you which component to go look at. ## 500 Internal Server Error 500 is the catch-all. It is what a framework returns when an exception escapes your handler. It carries no diagnostic information to the client by design — leaking a stack trace in a 500 body is an information-disclosure bug. Because 500 is generic, a spike of 500s almost always means "go read the origin's application logs"; the code itself will not narrow it down. A 500 is also, importantly, ambiguous about side effects. The request may have been half-applied — a row written before the failure, a message published. Clients must not assume nothing happened. ## 502 Bad Gateway 502 is only meaningful from an intermediary: a reverse proxy, an API gateway, a load balancer, a CDN edge. It means the intermediary acted as a gateway, forwarded the request, and could not obtain a valid response. Real causes: the origin process is not listening (connection refused), the origin crashed mid-response (connection reset), the origin returned bytes that are not valid HTTP, or a response header block exceeded the proxy's buffer limits. In every case the failing hop is between the proxy and origin, not the client. A useful mental test: if your application code never ran, the caller should not be seeing 500 — 502 is the honest code. ## 503 Service Unavailable 503 says: I am here, I understand you, I am choosing not to serve right now, and this is temporary. Legitimate triggers include load shedding when a queue or thread pool is saturated, a health check failing so the instance is draining, a graceful shutdown during a rolling deploy, a tripped circuit breaker in front of a sick dependency, and planned maintenance. 503 is the only 5xx that routinely carries `Retry-After`, because it is the only one where the server has a defensible opinion about when to come back. A load balancer with zero healthy backends typically synthesizes a 503 as well — there is nothing to forward to, which is different from forwarding and getting garbage. ## 504 Gateway Timeout 504 is the intermediary's timeout. The connection to upstream succeeded, the request was sent, and no complete response arrived before the proxy's read timeout expired. The classic driver is a slow dependency behind the origin — a locked database, a saturated downstream, a request doing far more work than the timeout budget allows. 504 is the most dangerous code for correctness reasoning: the origin may still be working on the request and may complete it after the client has already given up. Blind retries on 504 for a non-idempotent operation are how you get duplicate charges and duplicate orders. ## Reading them as a signal A quick triage table candidates should be able to produce: - Mostly 500 → origin application defect; read origin logs and traces. - Mostly 502 → origin is crashing, restarting, or not listening; check process health and deploy timing. - Mostly 503 → capacity, health checks, or lifecycle; check pool saturation, autoscaling and rollout state. - Mostly 504 → latency, not availability; check dependency latency and timeout budgets down the chain. ## Retry semantics 503 with `Retry-After` is the clearest retry invitation. 502 is usually retryable because the request very likely never reached application logic. 500 and 504 are the risky ones: application code did run and may have committed. The safe rule is that retry safety comes from the method's idempotency and any idempotency mechanism you built, not from the status code alone — the status only tells you whether retrying has any hope of succeeding.