В любой интеграции по API важно не только предусмотреть happy path (успешный путь), но и заранее описать, как система должна вести себя при ошибках.
📌 Что нужно сделать при проектировании ответов на API-запросы
0️⃣ Перечислить успешные ответы
+ 200 OK - Успех
+ 201 Created — Создано (новая запись в БД)
+ 202 Accepted — Принято в обработку (запрос принят, но обработка не завершена, часто используется при асинхронных задачах - отчёты, отправка email и др)
+ 204 No Content — Нет содержимого (запрос выполнен успешно, но в ответе нет тела)
1️⃣ Перечислить типовые ошибки и описать реакцию API на них:
+ 401 Unauthorized — Неверный логин/токен
+ 403 Forbidden — Нет прав
+ 429 Too Many Requests — Превышен лимит запросов
2️⃣ Добавить требования к специфичным ошибкам:
+ 400 Bad Request — Ошибка во входных данных
+ 409 Conflict — Создание дубликатов
+ 500 Internal Server Error — Внутренний сбой в работе сервера
+ и другие.
Все HTTP-статусы тут.
3️⃣ Добавить альтернативные сценарии в Use Case для API-метода, которые ведут к описанным в п.1 и 2 ошибкам.
2А. Клиент передал номер телефона в неверном формате.
→ Вернуть ошибку HTTP-400 и сообщение "Неверный формат номера телефона, ожидается 10 цифр"
4️⃣ Сделать JSON-структуру ответов об ошибках единообразной
{
"errorCode": "INVALID_PHONE",
"message": "Текст ошибки"
}
5️⃣ В OpenAPI спецификации (Swagger) добавить секции:
responses:
'400':
description: Неверные параметры запроса
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
6️⃣ Отразить примеры ошибок в документации Confluence и всегда иметь соответствующий раздел в шаблоне задачи.
Помните, что ошибки тоже важная часть программного интерфейса - API!
Если все ошибки задокументированны чётко и понятно, пользователи (и разработчики) будут вам благодарны, и вы сможете повысить UX приложений 🙌
🔗 Cтатья про документирование ошибок в REST API
#RestApiGA