Продолжим говорить про описание API и рассмотрим еще одну вещь, про которую часто забывают. И это ошибки. Точнее, как именно система их возвращает.
На моём опыте, если это не зафиксировать заранее, начинается хаос:
• в одном методе ошибка приходит строкой
• в другом объектом
• тексты разные, структура разная
И, как всегда, если что-то не описано, разработчики делают «как удобно», QA не понимает, что проверять, а фронт пишет костыли под каждый случай
Так что важно стандартизировать?
Я обычно фиксирую 2 вещи:
1. HTTP-коды
Минимальный базовый набор:
• 200 / 201 — успех
• 400 — ошибка запроса
• 401 / 403 — доступ
• 404 — не найдено
• 409 — конфликт
• 429 — превышен лимит
• 500 — внутренняя ошибка
Важно придерживаться единой логики во всех методах
2. Формат ошибки (самое важное)
Я почти всегда задаю единый формат:
{
"code": "INVALID_EMAIL",
"message": "Некорректный формат email",
"details": {
"field": "email"
}
}Что ещё важно продумать
• детализацию (какое поле, что не так)
• консистентность (одна ошибка = один формат всегда)
Важно! не забываем про безопасность
С одной стороны, ошибки должны быть понятными. С другой нельзя раскрывать внутреннюю логику системы.
Плохая практика писать в ошибках название метода в конкретном сервисе или детали SQL-запросов.
Поэтому я обычно придерживаюсь баланса: наружу понятное, но общее сообщение, внутрь (логи) уже полная техническая информация для разработчиков.
Всё это мы согласуем с командой, и сюрпризов возникнуть не должно.
Так что если проектируете API, обязательно продумайте этот блок.
Сохраняйте и используйте в работе ✔️