Status codes problem example added

src/en/drafts/HTTP Status Codes.md

@@ -6,7 +6,7 @@ As we discussed in the [Chapter 10](https://twirl.github.io/The-API-Book/docs/AP
 
 What the RFC fails to describe is what to do with the error. As we discussed, errors could be resolvable or not. If the error is unresolvable, all this status codes and headers stuff is simply irrelevant to clients, even more so to interim proxies. In fact, three error codes are enough:
   * `400` to denote persistent situation (error couldn't be resolved by just repeating the request);
-  * `404` to denote ‘uncertainity’ cases (the request could be repeated — possibly with different outcomes);
+  * `404` to denote ‘uncertainty’ cases (the request could be repeated — possibly with different outcomes);
   * `500` to denote server-side problems, with `Retry-After` header to indicate the desirable retry period.
 
 **Aside note:** mark a design flaw here. All `4xx` status codes are by default not cacheable, except for `404`, `405`, `410` and `414`, which are cacheable. We presume that editors of the spec did this with the best intentions, but the number of people who knows this nuance is probably quite close to the number of the spec editors. As a result, there are lots of cases (the author of this book had to deal with one) when `404`s were returned erroneously and cached on clients, thus prolonging the outage for an indefinite time.
@@ -35,6 +35,12 @@ Not only the number of status codes soared, but also their semantic meaning stir
 
 In a modern world we have to deal with a literal mess: HTTP status codes are used not for the protocol's purity sake, but to build the graphs; their semantic meaning forgotten; and clients often don't even try to get some useful information from the status codes, reducing them to the first digit. It's also a common practice to return resolvable errors as `200`s.
 
+As an example, a real situation the author of this book had to deal with: let's imagine we have an app, and there is a mistake in the code. If an authorization token is stall, it will be never renewed. Tokens become stall, for example, in 30 days, so this mistake wasn't found by QA engineers, and the app was released, for example, on June, 1. The release procedure was incremental: 1% of users got the release initially, then, gradually, it was shipped to everyone.
+
+After 30 days passed, on July, 1, we started to get some troubling support tickets, literally one or two. Several percent of 1% of auditory had troubles with authentication, but we couldn't see it: our `403` graphs looked normal, and when we examined specific users' logs, they look simply like users got their token expired somehow. So we didn't ring the bell and considered the problem being minor issue.
+
+Several days passed, more and more users got involved in the problem, until at some moment (30 days after the release hit 100% users) we've got instantly overloaded with reports, and all graphs went red. We spent several stressful hours looking for a problem cause, making hotfixes, and shipping a new release. All of this would have never happened, if we had had our graphs grouped by logical error reason, not only HTTP codes. If we had had a separate graph for the ‘token expired’ error, we would have noticed the numbers increasing sharply. But we hadn't. There was always a considerable number of `403`s on our graphs: banned users, robots, revoked tokens, etc.; the problem involving just several percent of several percent of users simply had no chance to caught our attention.
+
 #### So, what are you proposing, pal?
 
 Actually, there are three different approaches to solve this situation.

src/ru/drafts/HTTP Status Codes.md

@@ -38,6 +38,14 @@
 
 В современном мире мы буквально живём в этом бардаке: статус-коды HTTP используются вовсе не в целях поддержания чистоты протокола, а для графиков; их истинное значение забыто; клиенты обычно и не пытаются хоть какие-то выводы из кода ответа сделать, редуцируя его до первой цифры. (Честно говоря, ещё неизвестно, что хуже — игнорировать код или, напротив, писать логику поверх кодов, использованных не по назначению.) Ну и, конечно, нельзя не упомянуть о широко распространённой практике отдавать ошибки внутри `200`-ок.
 
+В качестве примера — реальная ситуация, с которой столкнулся автор этой книги. Давайте представим, что у нас есть приложение, и в его коде была допущена ошибка: если срок жизни токена авторизации истекал, приложение не могло его обновить. Срок жизни токенов был установлен, допустим, в 30 дней, так что QA-инженеры не обнаружили этой проблемы при тестировании, и релиз был успешно выпущен, скажем, первого июня. Процедура релиза была инкрементальной: сначала релиз раскатили на 1% пользователей, а потом постепенно довели процент до ста.
+
+По истечении 30 дней, первого июля, мы начали получать странные обращения в службу поддержки, буквально одно или два. Несколько процентов от 1% аудитории испытывали проблемы с аутентификацией, но мы этих проблем не видели: наши графики `403`-х ошибок выглядели нормально, а если мы смотрели в логи отдельных пользователей, то по ним у пользователя был просто просрочен токен почему-то. Поэтому никакой пожарной тревоги не прозвучало, и проблему посчитали малозначимой.
+
+Прошло ещё несколько дней, всё больше и больше пользователей сталкивалось с проблемой, пока в один прекрасный момент (через 30 дней после выкатывания релиза на 100% аудитории) нас не завалило обращениями. Все графики ушли в красную зону одномоментно. Следующие несколько часов выдались крайне непростыми, мы срочно разбирались в проблеме, готовили хотфикс и выкатывали новый релиз.
+
+Всего этого не случилось бы, если бы наши графики показывали логические причины ошибок. Если бы у нас был отдельный график количества токенов с истекшим сроком жизни — мы увидели бы на этом графике скачок. Но его не было. А на общем графике `403`-х всегда наблюдалось значительное количество ошибок (от забаненных пользователей, роботов, отозванных токенов и т.д.), на фоне которого проблемы нескольких процентов от нескольких процентов пользователей разглядеть было невозможно.
+
 #### А какие ваши предложения?
 
 На самом деле есть три подхода к решению этой ситуации: