Исправление ошибки: поле cf-turnstile-response обязательно

Сообщение "The cf-turnstile-response field is required" приходит из собственной валидации формы сайта и означает, что форма пришла без поля с таким именем или с пустым. Исправление зависит от того, кто отправил форму. В браузере виджет Turnstile не создал токен. В вашем собственном скрипте токен никто не запрашивал. В этом руководстве разобраны обе причины, а затем исправлен вариант со скриптом на Python с токеном от CapSkip.
Что означает сообщение
Это не ошибка Cloudflare. Слои валидации, например в Laravel, строят это предложение из имени поля по шаблону "The :attribute field is required", поэтому имя в сообщении совпадает с именем, которое сервер искал и не нашёл. Проверка выполняется до того, как сервер вообще обращается к Cloudflare. Когда сервер всё же обращается к endpoint siteverify без значения ответа, Cloudflare отвечает своим кодом missing-input-response, и это другое сообщение.
Согласно документации виджета Cloudflare скрытое поле с именем cf-turnstile-response создаётся для виджета внутри формы и уходит вместе с остальными полями. Поэтому поле существует только после того, как виджет отработал и выдал токен.
Почему поля нет
| Причина | Как понять | Исправить |
|---|---|---|
| Виджет так и не отрисовался | На странице нет окна Turnstile, а во вкладке Network браузера заблокирован запрос скрипта виджета | Разрешите скрипт и загружайте его по точному URL, который указывает Cloudflare, потому что, по словам Cloudflare, прокси-копия или кэшированная копия ломается при обновлениях |
| Виджет находится вне формы | Окно показано, но скрытое поле не находится внутри элемента form | Перенесите виджет в форму или скопируйте токен в поле самостоятельно |
| Форму отправили раньше, чем виджет закончил | Ошибка появляется, только если посетитель отправляет форму сразу, а со второй попытки всё работает | Отключайте кнопку отправки, пока виджет не выдаст токен |
| У поля другое имя | В сообщении названо другое поле, или страница задаёт своё имя поля ответа | Отправляйте то имя, которое показано в сообщении. В Cloudflare описана опция response-field-name, по умолчанию равная cf-turnstile-response |
| Поле ответа виджета отключено | Окно показано, но в форме нет поля cf-turnstile-response, а страница задаёт data-response-field равным false | Уберите эту настройку или считайте токен из callback виджета и поместите его в поле самостоятельно |
| Форму отправляет скрипт | Браузер не участвует, а отправка содержит только ваши собственные поля | Получите токен и отправьте его: этому посвящена остальная часть руководства |
Последняя строка единственная, которую можно исправить в коде, а сообщение помогает с именем поля: оно выводит имя, которое нужно серверу, поэтому скопируйте его точно. Столбец "Как понять" отражает моё понимание того, как ведёт себя виджет. Cloudflare документирует скрытое поле, опции response-field и response-field-name и правило про URL скрипта.
Что понадобится
- ПК с Windows и работающим CapSkip. На странице распознавание Cloudflare Turnstile перечислен запрос виджета: sitekey и адрес страницы.
- Python 3.10 или новее (нижняя граница, объявленная в capskip 1.7.0) и requests. Первая строка первого блока показывает команду pip, которая ставит оба пакета. Я запускал блоки на Python 3.11.7, 3.13.7 и 3.14.0 с capskip 1.7.0 и requests 2.34.2.
- Форма, в которую вам разрешено отправлять данные. В примере используется адрес-заглушка https://example.com/contact, форма со скрытым полем CSRF с именем _token, полем email и полем message.
- Для скрипта на другой машине переключите CapSkip в Server mode и передайте адрес этого ПК как host. Переключение описано в руководстве по установке, в разделе Настройки подключения. При запуске Server mode CapSkip принимает подключения с любого адреса. Чтобы оставить порт только для доверенных машин, добавьте блокирующее правило Windows Firewall для остальных.
Я запускал всё против двух имитаций, которые написал сам: одна изображает CapSkip, другая сайт с формой. Имитация сайта отклоняет отправку формы без поля и выводит сообщение из этого руководства. Все правила на ней мои, и я не отправлял ни одного задания в настоящее приложение CapSkip, поэтому ничто здесь не показывает, что реальный сайт примет токен.
Шаг 1: настройка сессии
Сохраните первый блок как turnstile_form.py. Два следующих блока добавляются в конец того же файла. Помощник read_input читает скрытое поле, а send_form отправляет ваши поля. Он выставляет заголовок Referer равным странице формы, как это делает браузер, потому что requests сам его не отправляет.
# python -m pip install capskip requests
import re
import requests
from capskip import CapSkip
FORM_URL = "https://example.com/contact" # the page that shows the form
# Local mode. In Server mode, use your server's address as the host.
solver = CapSkip(host="127.0.0.1", port=8080)
def read_input(html, name):
tag = re.search(r'<input[^>]*name="' + re.escape(name) + r'"[^>]*>', html)
value = re.search(r'value="([^"]*)"', tag.group(0)) if tag else None
return value.group(1) if value else None
def open_form():
session = requests.Session() # keeps the session cookie
return session, session.get(FORM_URL, timeout=30).text
def send_form(session, html, extra):
fields = {"_token": read_input(html, "_token"), "email": "[email protected]", "message": "Hello"}
fields.update(extra)
return session.post(FORM_URL, data=fields, headers={"Referer": FORM_URL}, timeout=30)Шаг 2: воспроизведите ошибку
Отправьте форму так, как обычно делает скрипт вначале: только со своими полями и ничем больше. Добавьте следующий блок. На моей имитации ответ имел статус 200, страница показывалась снова, а сообщение было в списке ошибок. Ваш сайт может сделать редирект или ответить 422, поэтому ищите это предложение в теле ответа.
session, html = open_form()
reply = send_form(session, html, {}) # no cf-turnstile-response at all
print(reply.status_code, re.findall(r"<li>(.*?)</li>", reply.text))
# 200 ['The cf-turnstile-response field is required.']Шаг 3: исправьте токеном от CapSkip
Возьмите sitekey из атрибута data-sitekey виджета, запросите у CapSkip токен методом turnstile и отправьте значение code из результата под точным именем поля. В документации API CapSkip сказано, что для Turnstile используется определённый User-Agent браузера, что вместе с токеном нужно отправлять тот же и что ответ его содержит. Блок копирует его в сессию, если он есть. Моя имитация его вернула, а что настоящее приложение возвращает для виджета, я не видел.
Токен работает один раз. Cloudflare сообщает, что каждый токен действителен 300 секунд и предназначен для одного использования, поэтому запрашивайте его прямо перед отправкой формы, а не в начале длинного скрипта. Если sitekey нет в атрибуте data-sitekey, потому что страница вызывает функцию render, скопируйте его из этого вызова один раз.
session, html = open_form()
sitekey = re.search(r'data-sitekey="([^"]+)"', html).group(1)
result = solver.turnstile(sitekey, FORM_URL)
if result.get("userAgent"): # the docs say the answer names the browser to present
session.headers["User-Agent"] = result["userAgent"]
reply = send_form(session, html, {"cf-turnstile-response": result["code"]})
print(reply.status_code, re.findall(r"<p>(.*?)</p>", reply.text))
# 200 ['Message sent. Thank you.'] (your site's success text will differ)На имитации все три версии Python дали такие результаты:
| Настройка имитации | Что произошло |
|---|---|
| Шаг 2, поле не отправлено | Сообщение появилось, а имитация CapSkip не получила ни одного задания |
| Шаг 3, токен отправлен под правильным именем | Одно задание, отправка формы принята |
| Сайт ожидает другое имя поля | Сообщение назвало другое поле, а отправка токена под ним была принята |
| Токен отправлен второй раз | Другое сообщение, "The captcha could not be verified", то есть поле было, но токен уже потрачен |
| Поле отправлено с пустым значением | То же сообщение об обязательном поле, поэтому пустое поле считается отсутствующим |
| Имитация настроена на проверку User-Agent | Токен без копирования возвращённого User-Agent был отклонён, а с копированием принят |
| Тот же токен, без заголовка Referer | 403 от имитации, правило которой требует Referer того же источника |
Читайте таблицу как проверку моей имитации. Формулировка сообщения, одноразовость и правило про Referer мои собственные, а настоящий сайт решает сам.
Если сообщение остаётся после добавления токена
- Другое сообщение, например о неудачной проверке, означает, что поле дошло. Посмотрите на токен: использован дважды, старше пяти минут или запрошен для другого адреса страницы.
FAQ
Ошибка обязательного поля cf-turnstile-response исходит от Cloudflare?
Нет. Это валидация сайта, которая сообщает об отсутствующем поле формы. Cloudflare подключается, только когда сайт отправляет токен на свой endpoint проверки.
Относится ли это к странице проверки Cloudflare?
Нет. Полноэкранная проверка не является полем формы. CapSkip отвечает на неё cookie, а этот метод описывает Документация API в отдельном разделе. Два дополнительных значения, которые нужны странице проверки Turnstile, показаны в руководствах по PHP и Node.js. Подробности смотрите в руководстве по решению Turnstile на PHP (там показано, как их отправлять), а версия для Node.js описана в руководстве по решению Turnstile на Node.js.
Может ли скрипт работать на другой машине, чем CapSkip?
Да, через Server mode. Укажите адрес ПК с CapSkip в качестве host. В руководстве по установке сказано, что статический публичный IP даёт самый стабильный удалённый доступ для серверной схемы, а Server mode требует запуска CapSkip от имени администратора. Распознавание по-прежнему идёт на вашем оборудовании с Windows, без оплаты за каждое решение.
Коротко
Ошибка означает, что сервер не увидел значения cf-turnstile-response. В браузере добейтесь, чтобы виджет отрисовался. В скрипте запросите токен прямо перед отправкой формы и отправьте его под именем из сообщения. Так как CapSkip работает на вашем ПК, это локальный сервис распознавания капчи без платы за каждое решение, поэтому на лицензионной копии каждая повторная попытка не требует доплаты. На странице сервиса распознавания капчи для Python перечислены остальные вызовы SDK, а Документация API даёт запрос в чистом виде.
