APITester| Status code | 502 |
|---|---|
| Status text | Bad Gateway |
| Category | 5xx Server Error |
| Response has body | Usually |
| Specification | RFC 9110 |
What does 502 Bad Gateway mean?
A server acting as a gateway or proxy received an invalid response from the upstream server. It belongs to the 5xx Server Error class, which means the server failed to fulfil an apparently valid request. The problem is on the server side.
When do APIs return 502?
The application behind a load balancer or reverse proxy is down, crashed, or returned garbage.
How to fix a 502 Bad Gateway
Usually transient and infrastructure-level. Retry with backoff. If it persists, the upstream application is likely not running or is crashing on startup — check whether the origin is healthy, not whether your request is valid.
Reproduce a 502 response
The fastest way to understand a status code is to trigger one and read the full response. Open the
API tester and send a request to https://httpbin.org/status/502 — you will
see the 502 status along with every response header the server sent. Comparing those headers against
a working request is often what reveals the cause.
When you are debugging a real endpoint, check the response headers as carefully as the body, and confirm you are using the right HTTP method for the operation.
Related 5xx status codes
500 Internal Server Error
The server hit an unexpected condition and could not complete the request.
501 Not Implemented
The server does not support the functionality required to fulfil the request.
503 Service Unavailable
The server is temporarily unable to handle the request.
504 Gateway Timeout
A gateway or proxy did not receive a timely response from the upstream server.
505 HTTP Version Not Supported
The server does not support the major HTTP version named in the request.
507 Insufficient Storage
The server cannot store the representation needed to complete the request.
502 Bad Gateway FAQ
What causes a 502 Bad Gateway error?
A proxy, load balancer or CDN received an invalid response, or none, from the server behind it. Typical causes are the application having crashed or restarting, a wrong upstream address or port, or the upstream closing the connection early.
What is the difference between 502 and 504?
With 502 the gateway got a bad or empty answer from the upstream server. With 504 Gateway Timeout it got no answer in time. A 502 suggests the upstream is down or broken; a 504 suggests it is too slow.
Can I fix a 502 error as a visitor?
Usually not, because the problem is between the site's own servers. Reloading after a minute often works, since many 502s happen during a deploy or restart. If it persists, the site operator has to fix it.
See also
- 503 Service Unavailable — The server is temporarily unable to handle the request.
- 504 Gateway Timeout — A gateway or proxy did not receive a timely response from the upstream server.
- 520 Web Server Returned an Unknown Error — Cloudflare reached the origin server and got back something it could not interpret as a valid HTTP response.
References
- RFC 9110, 502 Bad Gateway — The specification that defines this status code.
- MDN: 502 Bad Gateway — MDN's reference page for this status code.