🔗 Ссылка на полную статью
Проектирование API – это не только про описание успешных запросов и ответов, но и продуманная обработка ошибок.
Зачастую ошибки начинают всерьез обсуждать лишь после того, как тестировщик пишет в чат «ничего не работает» или «а это нормальное поведение?».
Однако прорабатывать возможные ошибки и формат ответов на них нужно заранее, на этапе системного анализа и разработки контрактов REST API методов. Да и в целом, не только REST, а любого API.
Что важно знать про ошибки в REST API:
✅ HTTP-код ошибки
Возвращается «снаружи» тела ответа.
Список HTTP-кодов стандартизирован (RFC 9110):
▫️ 2XX – ошибки нет, запрос принят и обработан успешно,
▫️ 4XX – ошибки на стороне клиента (проблемы с форматом или структурой запроса),
▫️ 5XX – на стороне сервера (проблемы во внутренней логике работы сервера - обращения в БД, проверки данных и другие)
👉 Полный перечень на русском
✅ Response Body: JSON-сообщение в дополнение к HTTP-коду
Стандартная структура сообщения об ошибке делает API понятным и удобным.
Хорошо продуманный ответ должен ясно объяснять проблему разработчику клиентского приложения, который использует API, и, косвенно, конечному пользователю.
Пример:
{
"error": "2020_VALIDATION_ERROR",
"message": "Данные не прошли валидацию.",
"details": {
"email": "Некорректный формат email.",
"age": "Возраст должен быть положительным числом."
},
"traceId": "c82f3d9b-12f0-487b-9eae-1d234e9f9123"
}
✅ Стандарт «Problem Details» (RFC 7807/9457) по проектированию ошибок в API
Предлагает единый формат JSON для сообщений об ошибках (MIME-тип application/problem+json).
Обновлен в 2023 году.
👉 Стоит сохранить ссылку на него в закладки.
✅ Примеры API-документации с примерами описания ошибок
👉 ЦИАН API
👉 Wieldberries API
Всю информацию с примерами собрала для вас в полном практическом руководстве:
🔗 Ссылка
Доступна в блоге GetAnalyst 🤝
#RestApiGA