HTTP 502 Bad Gateway

A gateway or proxy got an invalid response from the server behind it — a crash, a closed connection, garbage instead of HTTP.

Defined in RFC 9110 §15.6.3 — 502 Bad Gateway · MDN reference

Where you meet HTTP 502 in production

Load balancers and reverse proxies (nginx, a cloud load balancer, a CDN) in front of an application that crashed, restarted, ran out of memory or closed the connection mid-response.

Why you would test it

The upstream failure your monitoring confuses with your own. Test that clients retry idempotent requests with backoff, and that error pages do not blame the user.

What your client should do about a 502

Retry idempotent requests with exponential backoff; a 502 is often transient during deploys. For writes, retry only with an idempotency key — the upstream may have processed the request before failing.

502 versus the codes it gets confused with

Endpoints that return 502

1 endpoint in this playground answers with 502. Every one is free, needs no signup, and can be called from the browser or with curl.

Questions about HTTP 502

Is a 502 my code or the proxy?
Usually your application: the proxy is reporting that the application behind it failed to give a valid response.
Why do 502s appear during deploys?
The proxy routes to an instance that is shutting down or not yet ready, and gets a refused or reset connection.

Other server error codes

All HTTP status codes · All 39 mock REST APIs · Getting started guide

Last updated