docs: updates README.md

README.md

@@ -26,6 +26,7 @@ HTTP маршрутизатор для Node.js на основе
   - [Метаданные маршрута](#метаданные-маршрута)
   - [Состояние запроса](#состояние-запроса)
   - [Ветвление маршрутов](#ветвление-маршрутов)
+  - [Обработка ошибок](#обработка-ошибок)
 - [Отладка](#отладка)
 - [Тестирование](#тестирование)
 - [Лицензия](#лицензия)
@@ -410,6 +411,72 @@ v1Branch.defineRoute({
 // GET /api/v1/status
 ```
 
+## Обработка ошибок
+
+Маршрутизатор автоматически перехватывает любые ошибки, выброшенные из хуков
+или обработчика маршрута. По умолчанию, любая ошибка приводит к ответу сервера
+со статусом *500 Internal Server Error*.
+
+Для более гибкого управления HTTP-статусами рекомендуется использовать
+библиотеку [http-errors](https://www.npmjs.com/package/http-errors).
+Стандартный обработчик ошибок спроектирован для работы с данной библиотекой
+и автоматически извлекает `statusCode`, `message` и другие полезные свойства
+ошибки.
+
+```js
+import HttpErrors from 'http-errors';
+
+router.defineRoute({
+  method: HttpMethod.GET,
+  path: '/users/:id',
+  handler(ctx) {
+    const {id} = ctx.params;
+    const user = findUserById(id); // логика поиска пользователя
+    if (!user) {
+      // выброс ошибки 404 Not Found
+      // маршрутизатор поймает ошибку и отправит JSON-ответ
+      throw new HttpErrors.NotFound('Пользователь не найден');
+    }
+    if (!hasAccess(ctx.state.currentUser, user)) {
+      // ошибка 403 Forbidden с дополнительными данными
+      const error = new HttpErrors.Forbidden('Доступ запрещен');
+      error.code = 'ACCESS_DENIED';
+      error.details = {reason: 'Недостаточно прав'};
+      throw error;
+    }
+    return user;
+  },
+});
+```
+
+Структура ответа будет зависеть от данных, содержащихся в объекте ошибки.
+Например, ошибка `HttpErrors.NotFound` приведет к ответу со статусом `404`
+и телом, содержащим указанное сообщение.
+
+```json
+{
+  "error": {
+    "message": "Пользователь не найден"
+  }
+}
+```
+
+Если объект ошибки содержит дополнительные поля (например, `details`
+или `code`), они автоматически включаются в ответ. Это позволяет
+передавать клиенту более детальную информацию.
+
+```json
+{
+  "error": {
+    "code": "ACCESS_DENIED",
+    "message": "Доступ запрещен",
+    "details": {
+      "reason": "Недостаточно прав"
+    }
+  }
+}
+```
+
 ## Отладка
 
 Установка переменной `DEBUG` включает вывод логов.