5xx HTTP Status Codes

5xx status codes are server error responses.

This is an educational guide. The pages linked here are documentation pages served as 200 OK, even when the HTTP status code being explained is an error response.

What 5xx means

Server error responses mean the request may be valid, but the server, gateway, or upstream dependency failed while trying to handle it.

Where 5xx responses appear

Application code throws an unexpected error.
A reverse proxy or gateway cannot reach an upstream service.
The service is overloaded, down for maintenance, or timing out.
A server extension, negotiation step, or storage dependency fails.

Implementation notes

Use 500 for unexpected application failures that do not have a more specific status.
Use 502, 503, and 504 to distinguish bad upstream responses, temporary unavailability, and gateway timeouts.
Log server-side details, but keep public error responses short and free of secrets.

Compare similar 5xx codes

500 vs 502 vs 503 vs 504 Server Errors

All four are server-side failures, but they point to different layers of the system.

Code	Where to look first	Meaning
500	Application logs	The origin server hit an unexpected error.
502	Proxy and upstream logs	A gateway received an invalid upstream response.
503	Capacity and maintenance state	The service is temporarily unavailable.
504	Timeouts between proxy and upstream	A gateway waited too long for the upstream response.

Rules for every 5xx response

What RFC 9110 says about every 5xx response, quoted from the RFC.

SHOULD (server; content): Send a representation explaining the error and whether it is temporary or permanent. When: Any request except HEAD. Table row
Except when responding to a HEAD request, the server SHOULD send a representation containing an explanation of the error situation, and whether it is a temporary or permanent condition. RFC 9110 §15.6

The same rule is in the response obligations table and its JSON.

For an API, an RFC 9457 Problem Details body is one standard way to send that explanation.

All 5xx status codes

Code	Name	Meaning
500	Internal Server Error	The server encountered an unexpected condition that prevented it from fulfilling the request.
501	Not Implemented	The server either does not recognize the request method, or it lacks the ability to fulfill the request. Usually this implies future availability (e.g., a new feature of a web-service API).
502	Bad Gateway	The server, while acting as a gateway or proxy, received an invalid response from an inbound server it accessed while trying to fulfill the request.
503	Service Unavailable	The server is currently unable to handle the request because of a temporary overload or scheduled maintenance.
504	Gateway Timeout	The server, while acting as a gateway or proxy, did not receive a timely response from an upstream server it needed to complete the request.
505	HTTP Version Not Supported	The server does not support the HTTP protocol version used in the request.
506	Variant Also Negotiates	Transparent content negotiation for the request results in a circular reference.
507	Insufficient Storage	The server is unable to store the representation needed to complete the request.
508	Loop Detected	The server detected an infinite loop while processing the request (sent instead of 208 Already Reported).
509	Bandwidth Limit Exceeded	The server has exceeded the bandwidth specified by the server administrator; this is often used by shared hosting providers to limit the bandwidth of customers.
510	Not Extended	Further extensions to the request are required for the server to fulfill it.
511	Network Authentication Required	The client needs to authenticate to gain network access. Intended for use by intercepting proxies used to control access to the network (e.g., "captive portals" used to require agreement to Terms of Service before granting full Internet access via a Wi-Fi hotspot).
529	Site is overloaded	Used by Qualys in the SSLLabs server testing API to signal that the site can't process the request.
530	Site is frozen	Used by the Pantheon web platform to indicate a site that has been frozen due to inactivity.
598	Network read timeout error	Used by some HTTP proxies to signal a network read timeout behind the proxy to a client in front of the proxy.
599	Network Connect Timeout Error	An error used by some HTTP proxies to signal a network connect timeout behind the proxy to a client in front of the proxy.