re:re:actable
Урок 042 минуты чтения

Как формировать ответы и выбирать статус-коды?

На этой странице
Кратко

Код ответа должен кратко описывать результат, а JSON — содержать данные или понятное описание ошибки.

Вопрос

Как формировать ответы Express API и выбирать статус-коды для успеха и ошибок?

Успешные ответы

// Получение данных
response.status(200).json(users);
 
// Создание
response
  .status(201)
  .location(`/api/users/${createdUser.id}`)
  .json(createdUser);
 
// Удаление без тела
response.status(204).send();
КодКогда использовать
200 OKУспешное чтение или изменение с телом ответа
201 CreatedРесурс создан
204 No ContentДействие выполнено, тело не нужно

Ошибки клиента

КодЗначение
400Запрос имеет неверный формат
401Пользователь не подтверждён
403Пользователь известен, но действие запрещено
404Ресурс не найден
409Конфликт, например почта уже занята
422Формат понятен, но значения не проходят проверку
429Слишком много запросов

Команда может выбрать 400 или 422 для ошибок проверки данных. Важнее использовать выбранный подход последовательно.

Ошибки сервера

response.status(500).json({
  error: {
    code: "INTERNAL_ERROR",
    message: "Не удалось выполнить запрос",
  },
});

Не отправляй клиенту стек вызовов, SQL-запрос или пароль подключения.

Единый формат

Успех:

{
  "data": {
    "id": 42,
    "name": "Анна"
  }
}

Ошибка:

{
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "Пользователь не найден"
  }
}

Обёртка data необязательна. Главное — единообразие всего API.

json() или send()

  • json() преобразует значение в JSON и задаёт правильный тип содержимого;
  • send() подходит для текста, HTML или буфера;
  • для API чаще используется json().

Что важно помнить

  • 401 — пользователь не подтверждён, 403 — подтверждён, но действие запрещено.
  • 201 Created сопровождают заголовком Location с адресом нового ресурса.
  • Ответ 204 не содержит тела — клиент не должен вызывать на нём response.json().
  • Ответ 500 не раскрывает стек, SQL и параметры подключения.
  • Выбор между 400 и 422 для ошибок проверки — соглашение команды; важна последовательность.

Мини-шпаргалка

  • 200 — успех, 201 — создано, 204 — успех без тела.
  • 400 — неверный запрос, 404 — не найдено, 409 — конфликт.
  • 500 не должен раскрывать внутренние подробности.
  • Для созданного ресурса полезен заголовок Location.
  • Формат ошибок должен быть одинаковым во всём API.

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

MDN: HTTP response status codes, Express 5: API Reference.

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

Поиск

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