When to use it
Use 502 Bad Gateway when your server, acting as a gateway or proxy, got a response from the server behind it and that response was unusable. RFC 9110 defines it as a server that “received an invalid response from an inbound server it accessed while attempting to fulfill the request”.
The upstream did answer, and the answer was broken: a response that is not valid HTTP, a connection closed partway through the response, a body that is truncated or cannot be parsed, or a payload that does not match the contract the gateway depends on.
The same applies to an API that calls a third-party service on the client’s behalf, such as a payment processor or a shipping carrier, and relays the result. If that upstream returns something your service cannot use, 502 tells the client the fault is upstream of you and not in its request. A transparent proxy is different: when the upstream returns a well-formed 500, the proxy forwards that response unchanged, because it was a valid response.
502 is a server error, so the client did nothing wrong and the same request may succeed later. Upstream failures are often brief, so retrying a safe or idempotent request with backoff is reasonable. Do not retry a non-idempotent request automatically unless it carries an Idempotency-Key, because the upstream may have acted on it before its response broke.
When not to use it
Do not use it when the upstream never answered in time. That is gateway-timeout (504). The split is simple: 502 means the upstream answered badly; 504 means it did not answer before you gave up.
Do not use it when your own service is overloaded, in maintenance or deliberately shedding load. That is service-unavailable (503), which can carry Retry-After. If you know the upstream is down for a while (an open circuit breaker, a provider’s announced maintenance), 503 with Retry-After gives the client more to work with than a series of 502s.
Do not use it for a bug in your own code, including your code mishandling a perfectly valid upstream response. That is internal-server-error (500). Blaming the upstream for your own parsing bug sends whoever is on call to the wrong system.
Do not pass an upstream’s 4xx through as a 502. If the upstream rejected the request because of something the client sent, map it to the matching 4xx so the client can fix it.
Example response
{ "type": "https://apiguide.dev/errors/bad-gateway", "title": "Bad Gateway", "status": 502, "detail": "The payment provider returned an invalid response. The charge was not confirmed; retry with the same Idempotency-Key.", "instance": "/v1/charges", "upstream": "payments"}If you name the upstream, use a stable logical name such as payments, never an internal hostname, IP address or port. A 502 body is often generated by a proxy rather than your application, so configure the proxy’s error page to emit application/problem+json too, or clients will get an HTML page from an API endpoint.
