Server Error Codes: 500, 502, 503 and 504

The 5xx class says the server failed on a request that may have been perfectly valid. The specific code says where: 500 comes from the application itself, while 502 and 504 come from a gateway in front of it, such as a load balancer or API gateway, describing what went wrong with the server behind it, its upstream. 503 says the service is temporarily unable to answer at all.

Most APIs sit behind a gateway, so a client's request passes through two programs before anything answers. The diagram shows where each code is produced. The timings are illustrative.

500 Internal Server Error is the application saying something unexpected broke, usually an unhandled exception. It is the code a framework sends when the code has a bug.

502 Bad Gateway is the gateway saying it got an invalid answer from its upstream: the connection was refused, reset, or the reply was not valid HTTP. It often means the application crashed or is restarting.

503 Service Unavailable means the service cannot answer for now, because it is overloaded or down for maintenance. A Retry-After header tells the client when to come back.

504 Gateway Timeout is the gateway saying it waited for its upstream and gave up. The application may still be working on the request, and may yet finish it.

What the client should do next. Retry with a growing wait between attempts, but only requests whose method is idempotent or that carry an idempotency key. A 504 on a POST is the dangerous case: the order may have been created after the gateway stopped waiting.

So read a 502 or 504 as a message from the gateway about the application, and a 500 as a message from the application about itself.