# Bad Gateway

Source: https://apiguide.dev/errors/bad-gateway
Problem type URI: https://apiguide.dev/errors/bad-gateway
Status: 502 Bad Gateway
Updated: 2026-10-14

## 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`](/headers/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`](/headers/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

```json
{
  "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.