Ошибка precondition check failed появляется в ответе API, в консоли разработчика или в логах приложения, когда сервер отклоняет запрос из-за невыполненного предварительного условия — чаще всего из-за устаревшего тега версии ресурса ETag, отсутствующего или неверного заголовка If-Match либо конфликта параллельного изменения данных. Это не сбой сети и не «баг программы», а осознанный отказ сервера обрабатывать запрос в текущем виде.

Понимание механизма этой проверки позволяет устранить проблему за минуты: в одних случаях достаточно обновить кэш или повторить запрос, в других — скорректировать логику клиентского кода. Ниже разберём, откуда берётся ошибка, как диагностировать её источник и что делать разработчику и обычному пользователю.

Что означает ошибка precondition check failed

Сообщение precondition check failed — это текстовое описание отказа сервера выполнить запрос, потому что одно из условий, заданных клиентом, не выполнено. В протоколе HTTP этому соответствует статус 412 Precondition Failed, а в некоторых API и SDK (например, в gRPC и облачных сервисах) аналогичный смысл имеет код FAILED_PRECONDITION.

Механизм работает так. Клиент отправляет запрос с условными заголовками — например, If-Match со значением ETag ресурса. Сервер сравнивает присланное значение с актуальным состоянием данных. Если ресурс уже изменился (его правил другой пользователь или процесс), условие не выполняется, и сервер отвечает отказом, чтобы не перезаписать чужие изменения. Это защитный механизм, а не неисправность.

Важно различать два похожих случая:

  • 🔒 412 Precondition Failed — условие в заголовках запроса не совпало с состоянием ресурса на сервере;
  • ⚙️ FAILED_PRECONDITION в gRPC и SDK — операция невозможна в текущем состоянии системы, например удаление непустого каталога или вызов метода до инициализации;
  • 🌐 Ошибка в браузере или приложении — следствие устаревшего кэша, конфликта расширений или некорректной работы прокси.

Типичные причины появления ошибки

Наиболее частый сценарий — конфликт версий при конкурентном доступе. Два клиента читают один и тот же ресурс, первый сохраняет изменения, а второй при попытке записи получает отказ, потому что его ETag устарел. Так устроен оптимистичный контроль параллелизма, и это штатное поведение.

Вторая группа причин связана с клиентской стороной. Устаревший кэш браузера, повреждённые cookies, расширение, модифицирующее заголовки, или корпоративный прокси могут искажать условные заголовки. Тогда сервер получает запрос, который не соответствует его ожиданиям.

Третья группа — ошибки в коде клиента: заголовок If-Match сформирован с лишними кавычками или пробелами, используется значение ETag от другого ресурса, либо запрос отправлен до завершения обязательной инициализации SDK.

📊 Где вы столкнулись с ошибкой precondition check failed?