# Error Handling in API: Искусство обработки ошибок

> **Error Handling in API (Обработка ошибок в API)** — это комплекс методов и стандартов, позволяющих программному интерфейсу (API) корректно реагировать на нештатные ситуации, сбои или некорректные запросы, возвращая клиенту понятное описание проблемы вместо внезапного обрыва соединения.

## Почему правильная обработка ошибок так важна?

Представьте, что вы пришли в ресторан, заказали блюдо, а официант просто молча ушел и больше не вернулся. Вы не знаете: кончились ли продукты, закрылась ли кухня или он вас просто не услышал. Точно так же чувствует себя клиентское приложение, когда API не умеет правильно обрабатывать ошибки.

Грамотный **Error Handling** решает сразу несколько задач:

- **Информативность:** сообщает разработчику или системе, что именно пошло не так (например, неверный пароль или отсутствие прав).
- **Безопасность:** скрывает уязвимые детали внутренней работы сервера, выдавая только безопасную для публики информацию.
- **Стандартизация:** позволяет автоматизировать реакцию клиентского приложения на сбой.

## Как это работает на практике?

В основе обработки ошибок веб-API лежат стандартные статус-коды HTTP. Они делятся на классы:

- **4xx (Ошибки клиента):** проблема на стороне того, кто отправляет запрос. Например, **400 Bad Request** (неверный формат данных), **401 Unauthorized** (нет доступа) или знаменитая **404 Not Found** (ресурс не найден).
- **5xx (Ошибки сервера):** проблема на стороне самого API. Например, **500 Internal Server Error** (внутренняя ошибка сервера) или **503 Service Unavailable** (сервис перегружен).

### Пример хорошей и плохой обработки

**Плохой пример:** сервер возвращает статус 200 OK (успех), но в теле ответа пишет "status: error, message: Что-то пошло не так". Это путает системы мониторинга и усложняет жизнь разработчикам.

**Хороший пример:** сервер возвращает статус 422 Unprocessable Entity и подробный JSON-ответ:

**"error": { "code": 422, "message": "Некорректный email", "details": "Поле email не должно быть пустым" }**

Такой подход позволяет клиентскому приложению сразу подсветить красным нужное поле ввода на экране пользователя.

## Особенности в REST и GraphQL

Подходы к обработке ошибок могут сильно отличаться в зависимости от архитектурного стиля API.

В традиционных **REST API** краеугольным камнем являются именно HTTP-статусы. Вся инфраструктура интернета понимает эти коды. Если балансировщик видит много ошибок 500, он может автоматически перенаправить трафик на резервный сервер.

В **GraphQL** ситуация иная. Обычно GraphQL-сервер всегда возвращает статус 200 OK, даже если запрос завершился с ошибкой. Вся информация о сбоях помещается в специальный массив errors внутри JSON-ответа. Это связано с тем, что один запрос GraphQL может запрашивать множество разных сущностей: часть из них может быть успешно получена, а часть — выдать ошибку.

## Интересный факт: Ошибка 418 и чайники

В мире стандартизированных кодов ошибок есть место и для юмора. 1 апреля 1998 года инженер Ларри Мазинтер опубликовал шуточный документ, описывающий протокол управления кофеварками. В нем был введен статус-код **418 I am a teapot** (Я — чайник).

Этот код должен был возвращаться, если кто-то пытался заварить кофе в заварочном чайнике. Самое забавное, что эта шутка прижилась: сегодня многие популярные фреймворки официально поддерживают код 418, а некоторые разработчики используют его в своих API в качестве скрытой пасхалки.

## Лучшие практики Error Handling

Чтобы ваш API был по-настоящему надежным, эксперты рекомендуют придерживаться нескольких простых правил:

- **Используйте правильные HTTP-статусы.** Не возвращайте 500, если пользователь забыл указать логин.
- **Создайте единый стандарт** для ответов с ошибками, чтобы клиенты всегда знали, где искать описание проблемы.
- **Ведите логирование на сервере.** Клиент должен получить короткое и безопасное сообщение, а разработчик в логах — полную техническую картину сбоя.
- **Предоставляйте ссылки на документацию.** Идеальное сообщение об ошибке содержит URL, перейдя по которому, разработчик поймет, как исправить свой запрос.