feat(HTTP): Refresh 5XX response pages (mdn#35361)

* feat(http): Refresh 5xx response code pages * feat(http): Refresh 5xx response code pages * feat(http): Refresh 5xx response code pages * Apply suggestions from code review Co-authored-by: Hamish Willee <[email protected]> * feat(http): improvements based on reviewer feedback * Update files/en-us/web/http/status/510/index.md Co-authored-by: Hamish Willee <[email protected]> * Update files/en-us/web/http/status/503/index.md Co-authored-by: Hamish Willee <[email protected]> * feat(http): add details about how a server is capable of 503 responses when overloaded * feat(http): add details about 506 conditions * Apply suggestions from code review Co-authored-by: Hamish Willee <[email protected]> * feat(http): More cases for 503 conditions --------- Co-authored-by: Hamish Willee <[email protected]>
dwgrth · Aug 30, 2024 · f584f1b · f584f1b
1 parent c63daf6
commit f584f1b
Show file tree

Hide file tree

Showing 11 changed files with 443 additions and 58 deletions.
diff --git a/files/en-us/web/http/status/500/index.md b/files/en-us/web/http/status/500/index.md
@@ -7,20 +7,57 @@ spec-urls: https://www.rfc-editor.org/rfc/rfc9110#status.500
 
 {{HTTPSidebar}}
 
-The HyperText Transfer Protocol (HTTP) **`500 Internal Server Error`** server error response code indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.
+The HTTP **`500 Internal Server Error`** [server error response](/en-US/docs/Web/HTTP/Status#server_error_responses) status code indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.
+This error is a generic "catch-all" response to server issues, indicating that the server cannot find a more appropriate [5XX error](/en-US/docs/Web/HTTP/Status#server_error_responses) to respond with.
 
-This error response is a generic "catch-all" response. Usually, this indicates the server cannot find a better 5xx error code to response. Sometimes, server administrators log error responses like the 500 status code with more details about the request to prevent the error from happening again in the future.
+If you're a visitor seeing `500` errors on a web page, these issues require investigation by server owners or administrators.
+There are many possible causes of `500` errors, including: improper server configuration, out-of-memory (OOM) issues, unhandled exceptions, improper file permissions, or other complex factors.
+Server administrators may proactively log occurrences of server error responses, like the `500` status code, with details about the initiating requests to improve the stability of a service in the future.
 
 ## Status
 
 ```http
 500 Internal Server Error
 ```
 
+## Examples
+
+### 500 server error response
+
+The following request tries to fetch a webpage, but receives a 500 response in return.
+The response body contains a page describing the server state with a link to a support page for visitors.
+An identifier is contained in the response body for illustration of a method that may help server administrators narrow down the root cause of the problem:
+
+```http
+GET /highlights HTTP/1.1
+Host: example.com
+User-Agent: curl/8.6.0
+Accept: */*
+```
+
+```http
+HTTP/1.1 500 Internal Server Error
+Content-Type: text/html;
+Content-Length: 123
+
+<!doctype html>
+<html lang="en">
+<head>
+  <title>500 Internal Server Error</title>
+</head>
+<body>
+  <h1>Internal Server Error</h1>
+  <p>The server was unable to complete your request. Please try again later.</p>
+  <p>If this problem persists, please <a href="https://example.com/support">contact support</a>.</p>
+  <p>Server logs contain details of this error with request ID: ABC-123.</p>
+</body>
+</html>
+```
+
 ## Specifications
 
 {{Specifications}}
 
 ## See also
 
-- [HTTP Status Code Definitions](https://httpwg.org/specs/rfc9110.html#status.500)
+- [HTTP response status codes](/en-US/docs/Web/HTTP/Status)
diff --git a/files/en-us/web/http/status/501/index.md b/files/en-us/web/http/status/501/index.md
@@ -7,25 +7,52 @@ spec-urls: https://www.rfc-editor.org/rfc/rfc9110#status.501
 
 {{HTTPSidebar}}
 
-The HyperText Transfer Protocol (HTTP) **`501 Not Implemented`** server error response code means that **the server does not support the functionality required to fulfill the request**.
+The HTTP **`501 Not Implemented`** [server error response](/en-US/docs/Web/HTTP/Status#server_error_responses) status code means that the server does not support the functionality required to fulfill the request.
 
-This status can also send a {{HTTPHeader("Retry-After")}} header, telling the requester when to check back to see if the functionality is supported by then.
+A response with this status may also include a {{HTTPHeader("Retry-After")}} header, telling the client that they can retry the request after the specified time has elapsed.
+A `501` response is cacheable by default unless caching headers instruct otherwise.
 
-`501` is the appropriate response when the server does not recognize the request method and is incapable of supporting it for any resource. The only methods that servers are required to support (and therefore that must not return `501`) are {{HTTPMethod("GET")}} and {{HTTPMethod("HEAD")}}.
+`501` is the appropriate response when the server does not recognize the request method and is incapable of supporting it for any resource.
+Servers are required to support {{HTTPMethod("GET")}} and {{HTTPMethod("HEAD")}}, and therefore must not return `501` in response to requests with these methods.
+If the server does recognize the method, but intentionally does not allow it, the appropriate response is {{HTTPStatus("405", "405 Method Not Allowed")}}.
 
-If the server _does_ recognize the method, but intentionally does not support it, the appropriate response is {{HTTPStatus(405, "405 Method Not Allowed")}}.
+If you have visited a web page and you are seeing `501` errors, these issues require investigation and fixing by server owners or administrators.
+You can clear your browser cache for the domain, disable proxies if you are using one, or try again later to see if it works as expected.
 
-> [!NOTE]
->
-> - A 501 error is not something you can fix, but requires a fix by the web server you are trying to access.
-> - A 501 response is cacheable by default; that is, unless caching headers instruct otherwise.
+A `501` response can occur if proxies cannot not handle request methods used in the context of HTTP Extension Framework ({{RFC("2774")}}) applications.
+This status can also occur in Web Distributed Authoring and Versioning ({{Glossary("WebDAV")}}) when a request method (`SEARCH`, `PROPFIND`) does not have a URL handler configured to process it.
 
 ## Status
 
 ```http
 501 Not Implemented
 ```
 
+## Examples
+
+### Extension method not supported
+
+In the following HTTP Extension Framework example, a client sends a request with a mandatory extension specified in the `C-MAN` header.
+The {{HTTPHeader("Connection")}} header specifies that these extensions are to be handled on a [hop-by-hop](/en-US/docs/Web/HTTP/Headers#hop-by-hop_headers) basis.
+A proxy refuses to forward the `M-GET` method, and sends a `501` error in response:
+
+```http
+M-GET /document HTTP/1.1
+Host: example.com
+C-Man: "http://www.example.org/"
+Connection: C-Man
+```
+
+```http
+HTTP/1.1 501 Not Implemented
+```
+
 ## Specifications
 
 {{Specifications}}
+
+## See also
+
+- [HTTP response status codes](/en-US/docs/Web/HTTP/Status)
+- {{HTTPStatus("510", "510 Not Extended")}}
+- [HTTP 501 errors](https://learn.microsoft.com/en-us/aspnet/web-api/overview/testing-and-debugging/troubleshooting-http-405-errors-after-publishing-web-api-applications) in Microsoft ASP.NET documentation
diff --git a/files/en-us/web/http/status/502/index.md b/files/en-us/web/http/status/502/index.md
@@ -7,22 +7,60 @@ spec-urls: https://www.rfc-editor.org/rfc/rfc9110#status.502
 
 {{HTTPSidebar}}
 
-The HyperText Transfer Protocol (HTTP) **`502 Bad Gateway`** server error response code indicates that the server, while acting as a gateway or proxy, received an invalid response from the upstream server.
+The HTTP **`502 Bad Gateway`** [server error response](/en-US/docs/Web/HTTP/Status#server_error_responses) status code indicates that a server was acting as a gateway or {{Glossary("Proxy_server", "proxy")}} and that it received an invalid response from the upstream server.
 
-> [!NOTE]
-> A [Gateway](<https://en.wikipedia.org/wiki/Gateway_(telecommunications)>) might refer to different things in networking and a 502 error is usually not something you can fix, but requires a fix by the web server or the proxies you are trying to get access through.
+This response is similar to a {{HTTPStatus("500", "500 Internal Server Error")}} response in the sense that it is a generic "catch-call" for server errors.
+The difference is that it is specific to the point in the request chain that the error has occured.
+If the origin server sends a valid HTTP error response to the gateway, the response should be passed on to the client instead of a `502` to make the failure reason transparent.
+If the proxy or gateway did not receive any HTTP response from the origin, it instead sends a {{HTTPStatus("504", "504 Gateway Timeout")}} to the client.
+
+There are many causes of `502` errors, and fixing such problems probably requires investigation by server owners or administrators.
+Exceptions are client networking errors, particularly if the service works for other visitors, and if clients use VPNs or other custom networking setups.
+In such cases, clients should check network settings, firewall setup, proxy settings, DNS configuration, etc.
 
 ## Status
 
 ```http
 502 Bad Gateway
 ```
 
+## Examples
+
+### 502 gateway error response
+
+The following request tries to fetch a webpage, but receives a `502` response in return.
+The response body contains a page describing the server state with a link to a support page for visitors.
+
+```http
+GET /highlights HTTP/1.1
+Host: example.com
+User-Agent: curl/8.6.0
+Accept: */*
+```
+
+```http
+HTTP/1.1 502 Bad Gateway
+Content-Type: text/html;
+Content-Length: 123
+
+<!doctype html>
+<html lang="en">
+<head>
+  <title>502 Bad Gateway</title>
+</head>
+<body>
+  <h1>Bad Gateway</h1>
+  <p>The server was unable to complete your request. Please try again later.</p>
+  <p>If this problem persists, please <a href="https://example.com/support">contact support</a>.</p>
+</body>
+</html>
+```
+
 ## Specifications
 
 {{Specifications}}
 
 ## See also
 
-- {{HTTPStatus(504)}}
-- [HTTP Status Code Definitions](https://httpwg.org/specs/rfc9110.html#status.502)
+- [HTTP response status codes](/en-US/docs/Web/HTTP/Status)
+- {{HTTPStatus("504", "504 Gateway Timeout")}}
diff --git a/files/en-us/web/http/status/503/index.md b/files/en-us/web/http/status/503/index.md
@@ -7,26 +7,66 @@ spec-urls: https://www.rfc-editor.org/rfc/rfc9110#status.503
 
 {{HTTPSidebar}}
 
-The HyperText Transfer Protocol (HTTP) **`503 Service Unavailable`** server error response code indicates that the server is not ready to handle the request.
+The HTTP **`503 Service Unavailable`** [server error response](/en-US/docs/Web/HTTP/Status#server_error_responses) status code indicates that the server is not ready to handle the request.
 
-Common causes are a server that is down for maintenance or that is overloaded. This response should be used for temporary conditions and the {{HTTPHeader("Retry-After")}} HTTP header should, if possible, contain the estimated time for the recovery of the service.
+Common causes are that a server is down for maintenance or overloaded.
+During maintenance, server administrators may temporarily route all traffic to a `503` page, or this may happen automatically during software updates.
+In overload cases, some server-side applications will reject requests with a `503` status when resource thresholds like memory, CPU, or connection pool limits are met.
+Dropping incoming requests creates backpressure that prevents the server's compute resources from being exhausted, avoiding more severe failures.
+If requests from specific clients are being restricted due to {{Glossary("Rate_limit", "rate limiting")}}, the appropriate response is {{HTTPStatus("429", "429 Too Many Requests")}}.
 
-> [!NOTE]
-> Together with this response, a user-friendly page explaining the problem should be sent.
+This response should be used for temporary conditions and the {{HTTPHeader("Retry-After")}} HTTP header should contain the estimated time for the recovery of the service, if possible.
+
+A user-friendly page explaining the problem should be sent along with this response.
 
-Caching-related headers that are sent along with this response should be taken care of, as a 503 status is often a temporary condition and responses shouldn't usually be cached.
+> [!NOTE]
+> Caching-related headers sent with this response require special attention; a `503` indicates a temporary issue and responses shouldn't usually be cached as clients may receive outdated error pages after a fix has been deployed.
 
 ## Status
 
 ```http
 503 Service Unavailable
 ```
 
+## Examples
+
+### 503 server error response
+
+The following request tries to fetch a webpage, but receives a `503` response.
+The response body contains a page describing the server state with a link to a support page for visitors.
+An identifier is contained in the response body for illustration of a method that may help server administrators narrow down the root cause of the problem:
+
+```http
+GET /highlights HTTP/1.1
+Host: example.com
+User-Agent: curl/8.6.0
+Accept: */*
+```
+
+```http
+HTTP/1.1 503 Service Unavailable
+Content-Type: text/html;
+Content-Length: 123
+
+<!doctype html>
+<html lang="en">
+<head>
+  <title>503 Service Unavailable</title>
+</head>
+<body>
+  <h1>503 Service Unavailable</h1>
+  <p>The server was unable to complete your request. Please try again later.</p>
+  <p>If this problem persists, please <a href="https://example.com/support">contact support</a>.</p>
+  <p>Server logs contain details of this error with request ID: ABC-123.</p>
+</body>
+</html>
+```
+
 ## Specifications
 
 {{Specifications}}
 
 ## See also
 
+- [HTTP response status codes](/en-US/docs/Web/HTTP/Status)
 - {{HTTPHeader("Retry-After")}}
-- [HTTP Status Code Definitions](https://httpwg.org/specs/rfc9110.html#status.503)
diff --git a/files/en-us/web/http/status/504/index.md b/files/en-us/web/http/status/504/index.md
@@ -7,22 +7,56 @@ spec-urls: https://www.rfc-editor.org/rfc/rfc9110#status.504
 
 {{HTTPSidebar}}
 
-The HyperText Transfer Protocol (HTTP) **`504 Gateway Timeout`** server error response code indicates that the server, while acting as a gateway or proxy, did not get a response in time from the upstream server that it needed in order to complete the request.
+The HTTP **`504 Gateway Timeout`** [server error response](/en-US/docs/Web/HTTP/Status#server_error_responses) status code indicates that the server, while acting as a gateway or {{Glossary("Proxy_server", "proxy")}}, did not get a response in time from the upstream server in order to complete the request.
+This is similar to a {{HTTPStatus("502", "502 Bad Gateway")}}, except that in a `504` status, the proxy or gateway did not receive any HTTP response from the origin within a certain time.
 
-> [!NOTE]
-> A [Gateway](<https://en.wikipedia.org/wiki/Gateway_(telecommunications)>) might refer to different things in networking and a 504 error is usually not something you can fix, but requires a fix by the web server or the proxies you are trying to get access through.
+There are many causes of `504` errors, and fixing such problems likely requires investigation and debugging by server administrators, or the site may work again at a later time.
+Exceptions are client networking errors, particularly if the service works for other visitors, and if clients use VPNs or other custom networking setups.
+In such cases, clients should check network settings, firewall setup, proxy settings, DNS configuration, etc.
 
 ## Status
 
 ```http
 504 Gateway Timeout
 ```
 
+## Examples
+
+### 504 gateway timeout response
+
+The following request tries to fetch a webpage, but receives a `504` response in return.
+The response body contains a page describing the server state with a link to a support page for visitors.
+
+```http
+GET /highlights HTTP/1.1
+Host: example.com
+User-Agent: curl/8.6.0
+Accept: */*
+```
+
+```http
+HTTP/1.1 504 Gateway Timeout
+Content-Type: text/html;
+Content-Length: 123
+
+<!doctype html>
+<html lang="en">
+<head>
+  <title>504 Gateway Timeout</title>
+</head>
+<body>
+  <h1>Gateway timeout</h1>
+  <p>The server did not respond in time. Please try again later.</p>
+  <p>If this problem persists, please <a href="https://example.com/support">contact support</a>.</p>
+</body>
+</html>
+```
+
 ## Specifications
 
 {{Specifications}}
 
 ## See also
 
-- [HTTP Status Code Definitions](https://httpwg.org/specs/rfc9110.html#status.504)
-- {{HTTPStatus(502)}}
+- [HTTP response status codes](/en-US/docs/Web/HTTP/Status)
+- {{HTTPStatus("502", "502 Bad Gateway")}}
diff --git a/files/en-us/web/http/status/505/index.md b/files/en-us/web/http/status/505/index.md
@@ -7,9 +7,10 @@ spec-urls: https://httpwg.org/specs/rfc9110.html#status.505
 
 {{HTTPSidebar}}
 
-The HyperText Transfer Protocol (HTTP)
-**`505 HTTP Version Not Supported`** response status code
-indicates that the HTTP version used in the request is not supported by the server.
+The HTTP **`505 HTTP Version Not Supported`** [server error response](/en-US/docs/Web/HTTP/Status#server_error_responses) status code indicates that the HTTP version used in the request is not supported by the server.
+
+It's common to see this error when a request line is improperly formed such as `GET /path to resource HTTP/1.1` or with `\n` terminating the request line instead of `\r\n`.
+For example, intermediaries such as load balancers may not handle request lines of a forwarded request as illustrated in the example below.
 
 ## Status
 
@@ -21,6 +22,38 @@ indicates that the HTTP version used in the request is not supported by the serv
 
 {{Specifications}}
 
+## Examples
+
+### A 505 due to malformed request-line
+
+In the following example, a client requests `example.com/dog%20trainers`, but due to incorrect load balancer configuration, the {{Glossary("Percent-encoding", "percent encoding")}} in the URL is not handled properly.
+In this case, the origin server sees `trainers` instead of the HTTP version, and a `505` response is returned instead.
+A request identifier is contained in the response body for illustration of a way that may help server administrators narrow down the root cause of the problem:
+
+```http
+GET /dog trainers HTTP/1.1
+Host: example.com
+```
+
+```http
+HTTP/1.1 505 HTTP Version Not Supported
+Content-Type: text/html;
+Content-Length: 123
+
+<!doctype html>
+<html lang="en">
+<head>
+  <title>505 HTTP Version Not Supported</title>
+</head>
+<body>
+  <h1>505 HTTP Version Not Supported</h1>
+  <p>If this problem persists, please <a href="https://example.com/support">contact support</a>.</p>
+  <p>Server logs contain details of this error with request ID: ABC-123.</p>
+</body>
+</html>
+```
+
 ## See also
 
-- {{HTTPHeader("Upgrade")}}
+- [HTTP response status codes](/en-US/docs/Web/HTTP/Status)
+- {{HTTPHeader("Upgrade")}} header