re:re:actable
Урок 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.

Документация

RFC 9457: Problem Details for HTTP APIs, MDN: Коды ответа.

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам