corrections

src/en/clean-copy/05-[Work in Progress] Section IV. HTTP APIs & REST Architectural Principles/07.md

@@ -49,4 +49,14 @@ A more interesting question is then what the client can (or must) do if such an
 
 If we try to apply this principle to HTTP APIs, we will soon learn that the situation is complicated. On one hand, the protocol includes a lot of codes that indicate specific problems with using the protocol, such as `405 Method Not Allowed` (indicates that the verb in the request cannot be applied to the requested resource), `406 Not Acceptable` (the server cannot return a representation that satisfies the `Accept*` headers in the request), `411 Length Required`, `414 URI Too Long`, etc. The client code might process these errors and sometimes even perform some actions to mitigate them (for example, add a `Content-Length` header in case of a `411` error). However, this is hardly applicable to business logic. If the server returned a `429 Too Many Request` if some limit is exceeded, there are no standardized means of indicating *what exact limit* was hit.
 
-Sometimes, the absence of a common approach to describing business logic errors is circumvented by using different codes with almost identical semantics (or just randomly chosen codes) to distinguish between different causes of the error. One notable example is the widely adopted usage of the `401 Authorized` status code to indicate the absence or the invalid value of authorization headers, which is a signal for an application to ask the user to log in. This usage contradicts the standard (which requires that a `401` response must contain the `WWW-Authenticate` header that describes the methods of authorization; we are unaware of a single API that follows this requirement), but it has become a *de facto* standard itself.
+Sometimes, the absence of a common approach to describing business logic errors is circumvented by using different codes with almost identical semantics (or just randomly chosen codes) to distinguish between different causes of the error. One notable example is the widely adopted usage of the `401 Authorized` status code to indicate the absence or the invalid value of authorization headers, which is a signal for an application to ask the user to log in. This usage contradicts the standard (which requires that a `401` response must contain the `WWW-Authenticate` header that describes the methods of authorization; we are unaware of a single API that follows this requirement), but it has become a *de facto* standard itself.
+
+Even if we choose this approach, there are very few status codes that can reflect different aspects of the same error type. In fact, we face the situation that all the multiplicity of business-bound errors is to be returned using a very limited set of status codes:
+  * `400 Bad Request` for all the errors related to request validation issues. (Some purists insist that `400` corresponds to format violations such as invalid JSON. For logical errors, the `422 Unprocessable Content` code is to be used. This actually changes nothing regarding the discussed problem.)
+  * `403 Forbidden` for any problems related to authorizing the user's actions.
+  * `404 Not Found` if any of the entities referred in the request are non-existent *or* if exposing the real cause of the error is undesirable.
+  * `409 Confict` if data integrity is violated.
+  * `410 Gone` if the resource was deleted.
+  * `429 Too Many Requests` if some quotas are exceeded.
+
+The editors of the specification are very well aware of this problem as they state that “the server SHOULD send a representation containing an explanation of the error situation, and whether it is a temporary or permanent condition.” This, however, contradicts the entire idea of a uniform interface. (Let us additionally emphasize that this lack of standard tools to describe business logic-bound errors is one of the reasons we consider the REST architectural style as described by Fielding in his 2008 article non-viable. The client *must* possess prior knowledge of error formats and how to work with them. Otherwise, it could restore its state after an error only by restarting the application.)