Урок 052 минуты чтения
Как проектировать ошибки в REST API?
На этой странице
Кратко
Хороший REST API возвращает не только status code, но и понятное тело ошибки: message, code, details, field errors и trace id. Это помогает frontend показать пользователю нормальное сообщение и ускоряет debugging.
Вопрос
Как должен выглядеть ответ с ошибкой в REST API, чтобы frontend мог его корректно обработать?
Плохой error response
{
"error": "Error"
}Frontend не понимает:
- что произошло;
- можно ли повторить;
- какое поле подсветить;
- что показать пользователю;
- что отправить в bug report.
Хороший error response
{
"statusCode": 422,
"code": "VALIDATION_ERROR",
"message": "Validation failed",
"fields": [
{
"path": "email",
"message": "Invalid email"
}
],
"requestId": "req_123"
}Зачем нужен machine-readable code?
message может меняться и переводиться. code можно использовать в логике:
if (error.code === 'EMAIL_ALREADY_EXISTS') {
setFieldError('email', 'Этот email уже занят');
}Не раскрывай лишнее
Плохой production response:
{
"message": "Cannot read properties of undefined",
"stack": "..."
}Stack trace нужен в logs, а не в response пользователю.
Что важно помнить
- Есть стандарт Problem Details (RFC 9457): поля
type,title,status,detail,instanceиContent-Type: application/problem+json. - Сообщения для пользователя лучше формировать на frontend по
code: так проще локализация. - Не различайте «пользователь не найден» и «неверный пароль» в ответе на вход — это помогает перебирать email.
requestId(или trace id) стоит показывать в UI ошибки: пользователь передаст его в поддержку.
Мини-шпаргалка
- Status code показывает класс ошибки.
- Body ошибки должен быть предсказуемым.
codeполезен для frontend logic.- Field errors нужны для форм.
requestIdпомогает искать ошибку в logs.- Stack trace нельзя отдавать в production response.
Документация
Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.