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

cf-turnstile-response field is required - Fix: The cf-turnstile-response Field Is Required Error

Сообщение "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 был отклонён, а с копированием принят
Тот же токен, без заголовка Referer403 от имитации, правило которой требует 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 даёт запрос в чистом виде.