Как обработать ответ 404 при поиске по API, когда ничего не найдено?

HTTP-статус 404 означает, что сервер не нашёл ресурс по указанному URL. В контексте поиска по API это нормальная ситуация: пользователь ввёл запрос, по которому ничего не совпало. Важно не путать 404 с ошибками 500 или сетевыми сбоями — это разные категории, и обрабатывать их нужно по-разному.

Почему fetch не бросает ошибку при 404

Метод fetch отклоняет промис только при сетевых сбоях (нет соединения, DNS не разрешился). Если сервер ответил любым HTTP-статусом, включая 404 или 500, промис успешно разрешается. Поэтому проверять нужно вручную через response.ok или response.status.

Пример обработки

async function searchItems(query) {
  const res = await fetch(`/api/search?q=${encodeURIComponent(query)}`);

  if (res.status === 404) {
    // Ничего не найдено — это не ошибка, а пустой результат
    return { items: [], notFound: true };
  }

  if (!res.ok) {
    // 500, 403 и прочие — реальные ошибки
    throw new Error(`Request failed: ${res.status}`);
  }

  return { items: await res.json(), notFound: false };
}

// Использование
try {
  const { items, notFound } = await searchItems('react');
  if (notFound) showEmptyState('Ничего не найдено');
  else renderList(items);
} catch (e) {
  showError('Что-то пошло не так, попробуйте позже');
}

Что важно учесть

• Различайте 404 (ресурс не найден) и 200 с пустым массивом — некоторые API возвращают пустой список вместо 404, и это тоже валидный сценарий.
• Не показывайте пользователю технический текст ошибки — используйте понятное сообщение и, при необходимости, кнопку «Сбросить фильтры».
• Логируйте 404 отдельно от 5xx, чтобы не засорять алерты ложными срабатываниями.
• В UI различайте состояния: загрузка, пустой результат, ошибка сети — это три разных экрана.

Итог: 404 при поиске — это ожидаемый результат, а не сбой. Обрабатывайте его как отдельное состояние «ничего не найдено», отделяя от настоящих ошибок, чтобы приложение оставалось предсказуемым и удобным для пользователя.