Ошибка 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.
Диагностика: как найти источник проблемы
Начните с того, что посмотрите полный ответ сервера, а не только текст ошибки. В браузере откройте инструменты разработчика (клавиша F12), вкладку Network, найдите неудачный запрос и изучите его статус-код, заголовки запроса и ответа. Именно там видно, какое условие не выполнено.
Если вы работаете с API программно, воспроизведите запрос вручную через curl или Postman — это отделит проблемы вашего кода от поведения самого сервера:
curl -v -X PUT https://api.example.com/resource/1 \
-H "If-Match: \"ваш-etag\"" \
-H "Content-Type: application/json" \
-d '{"field": "value"}'
Обратите внимание на заголовок ETag в ответе сервера при GET-запросе — именно его актуальное значение нужно подставлять в If-Match при изменении ресурса. Если GET и PUT выполняются с заметной паузой, ресурс мог успеть измениться между ними.
Сохраняйте ETag из последнего GET-ответа и подставляйте его в If-Match непосредственно перед запросом на изменение — чем короче пауза, тем ниже вероятность конфликта версий.
Решение для разработчиков и интеграций API
Если ошибка возникает в вашем коде, действуйте по следующему чек-листу.
☑️ Проверка запроса при ошибке precondition check failed
Правильный паттерн работы с условными запросами — цикл «прочитать → изменить → записать с проверкой версии». При получении отказа не нужно просто повторять тот же запрос: условие не изменится. Вместо этого заново прочитайте ресурс, примените свои изменения к свежей версии и отправьте запрос снова.
⚠️ Внимание: не удаляйте заголовок If-Match и не заменяйте его на «звёздочку» ради избавления от ошибки, если сервер не требует этого по документации. Так вы отключите защиту от потери обновлений и рискуете молча перезаписать чужие данные.
Для ошибок вида FAILED_PRECONDITION в SDK и облачных сервисах логика иная: читайте текстовое описание в ответе — там обычно указано, какое именно состояние не подходит. Типичные случаи: операция над объектом, который ещё не создан или уже удалён, вызов метода до завершения инициализации клиента, удаление контейнера, в котором остались элементы. Конкретные требования зависят от сервиса, поэтому сверяйтесь с его официальной документацией.
Решение для пользователей браузера и приложений
Если вы не разработчик, а ошибка появляется при обычной работе с сайтом или приложением, начните с простых обратимых действий. Обновите страницу принудительно, минуя кэш: в большинстве браузеров это сочетание Ctrl+F5 (или Cmd+Shift+R на macOS). Это заставит браузер запросить свежие версии ресурсов.
Если обновление не помогло, очистите кэш и cookies для конкретного сайта через настройки браузера и попробуйте открыть страницу в режиме инкогнито — так вы исключите влияние расширений. В приложениях помогает выход из учётной записи и повторный вход: при этом клиент получает свежие токены и служебные данные.
Почему режим инкогнито помогает диагностировать проблему
В приватном окне браузер не использует сохранённый кэш, cookies и большинство расширений. Если в инкогнито ошибка исчезает, причина почти наверняка в локальных данных или дополнениях. Если ошибка остаётся и там — проблема на стороне сервера или в самом запросе приложения.
Когда ошибка воспроизводится только у вас и на любом устройстве, а сайт у других работает, возможная причина — устаревшая версия приложения. Проверьте наличие обновлений в магазине приложений или на официальном сайте программы.
Сравнение похожих ошибок
Чтобы не тратить время на неверное направление диагностики, полезно отличать precondition check failed от смежных отказов сервера.
| Ошибка | Смысл | Типичная причина |
|---|---|---|
412 Precondition Failed | Условие запроса не выполнено | Устаревший ETag, конфликт версий |
409 Conflict | Запрос противоречит состоянию ресурса | Дубликат записи, конфликт данных |
428 Precondition Required | Сервер требует условный запрос | Отсутствует заголовок If-Match |
FAILED_PRECONDITION (gRPC) | Неверное состояние системы для операции | Операция до инициализации, непустой объект |
Особое внимание обратите на статус 428: это обратная ситуация — сервер требует, чтобы клиент обязательно присылал условные заголовки, и отказывает в их отсутствие. Решение — добавить корректный If-Match, а не убирать условия.
Ошибка precondition check failed — это защитный механизм, а не сбой: сервер отказывается выполнять запрос, чтобы не перезаписать актуальные данные устаревшей версией. Устраняется обновлением состояния клиента, а не повтором того же запроса.
Когда ошибка на стороне сервера
Иногда клиент всё делает правильно, а отказ продолжает приходить. Возможная причина — некорректная генерация ETag на сервере, рассинхронизация между узлами распределённой системы или ошибка в промежуточном кэше. Признаки: свежеполученный ETag сразу отклоняется, ошибка воспроизводится у разных клиентов и в разных сетях.
В такой ситуации со стороны пользователя остаётся собрать диагностическую информацию — время запроса, полные заголовки, текст ответа — и передать её в поддержку сервиса. Самостоятельно исправить серверную логику невозможно, а попытки обойти защиту могут привести к потере данных.
⚠️ Внимание: если сервис рабочий и в нём хранятся важные данные, не пытайтесь массово перезаписывать объекты без условных заголовков. При конфликте версий сначала выгрузите актуальное состояние и сравните его со своими изменениями.
⚠️ Внимание: в корпоративной сети ошибку может провоцировать прокси или шлюз, изменяющий заголовки. Проверьте тот же запрос из другой сети — если он проходит, передайте информацию сетевому администратору.
Профилактика повторного появления
Для разработчиков главная профилактика — корректная реализация паттерна оптимистичного контроля версий: всегда читать ресурс перед изменением, передавать актуальный ETag и обрабатывать отказ 412 повторным чтением, а не слепым повтором. Стоит также логировать полные заголовки неудачных запросов — это ускоряет разбор инцидентов.
Пользователям помогает регулярное обновление браузера и приложений, умеренность в установке расширений, меняющих сетевые запросы, и периодическая очистка кэша проблемных сайтов. Эти меры устраняют клиентские причины, не затрагивая серверную логику.
Главное правило диагностики: смотрите полный ответ сервера и заголовки запроса. Текст ошибки говорит «что» случилось, а заголовки показывают «почему».
Часто задаваемые вопросы
Опасна ли ошибка precondition check failed для моих данных?
Нет, наоборот — она защищает данные. Сервер отказывается выполнять запрос именно для того, чтобы не перезаписать актуальную информацию устаревшей версией. Сами данные при этом не повреждаются.
Поможет ли простое повторение запроса?
Как правило, нет. Условие, которое не выполнилось, останется прежним, и сервер снова откажет. Нужно обновить состояние клиента: заново получить ресурс, актуальный ETag или свежие данные страницы, и только затем повторить операцию.
Чем отличается 412 Precondition Failed от FAILED_PRECONDITION?
Первый — стандартный HTTP-статус, связанный с условными заголовками запроса. Второй — код ошибки в gRPC и ряде SDK, означающий, что система находится в состоянии, не подходящем для операции (например, вызов до инициализации). Причины и способы устранения у них разные.
Почему ошибка появляется только у меня, а у коллег всё работает?
Вероятная причина — локальные факторы: устаревший кэш браузера, расширение, изменяющее заголовки, старая версия приложения или прокси в вашей сети. Проверьте работу в режиме инкогнито и из другой сети, чтобы сузить круг поиска.
Можно ли отключить проверку предусловий на сервере?
Технически разработчик сервера может не требовать условные заголовки, но делать этого не стоит: механизм предохраняет от потери обновлений при параллельной работе. Корректное решение — чинить клиентскую логику, а не снимать защиту.