How Cloudflare Turnstile Works

What Turnstile is

Cloudflare's Turnstile documentation calls it a "smart CAPTCHA alternative". Instead of asking the visitor to pick traffic lights, it runs short, non-interactive JavaScript checks in the browser. Cloudflare lists the kinds of checks it uses: proof-of-work puzzles, proof-of-space, probing for web APIs and other browser-environment signals. The outcome adapts to the visitor: most people see a spinner for a moment or nothing at all, and a smaller share are asked to tick a box.

Two properties surprise people. First, Turnstile does not require the site to route traffic through Cloudflare; the docs state it "can be embedded into any website without sending traffic through Cloudflare". A Turnstile loop on a site that is not on Cloudflare is still a Turnstile loop. Second, Turnstile is not the same thing as a Cloudflare WAF challenge page, the full-screen "verify you are human" interstitial a Cloudflare-proxied site can show. They share technology, and one can satisfy the other through pre-clearance (covered below), but they are configured in different places.

On Apple devices and some other browsers, Turnstile can also use Private Access Tokens, issued under the Privacy Pass HTTP authentication scheme, which let the device vouch for itself without revealing who the user is. Cloudflare's troubleshooting page notes that a 401 response in the console usually relates to this and can generally be ignored when a token is still issued.

Widget modes

A site owner picks one of three widget modes, defined on Cloudflare's widget concepts page. The mode changes what a visitor sees; the server-side check described in the next section is the same for all three.

Server validation

The browser side only produces a token. The site's backend has to send that token to Cloudflare's Siteverify endpoint, and the server-side validation guide is blunt about it: "The client-side widget alone does not protect your forms." Each token is valid for 300 seconds and can be validated once; a second check of the same token fails with timeout-or-duplicate.

A minimal, tested validation function in Python:

"""Validate a Turnstile token on your server before trusting the form it came with."""
import os

import requests

SITEVERIFY = "https://challenges.cloudflare.com/turnstile/v0/siteverify"


def verify(token: str, remote_ip: str | None = None, expected_hostname: str | None = None) -> tuple[bool, list[str]]:
    payload = {"secret": os.environ["TURNSTILE_SECRET"], "response": token}
    if remote_ip:
        payload["remoteip"] = remote_ip
    result = requests.post(SITEVERIFY, data=payload, timeout=10).json()
    errors = result.get("error-codes", [])
    if not result.get("success"):
        return False, errors
    if expected_hostname and result.get("hostname") != expected_hostname:
        return False, ["hostname-mismatch"]
    return True, errors

We ran it against Cloudflare's published test secrets on October 30, 2026. The always-pass secret returned success, the always-fail secret returned invalid-input-response, and the spent-token secret returned timeout-or-duplicate, which is the same code a real double submission produces.

Two server-side mistakes cause loops that look like bot detection: validating the token twice (once in middleware, once in the handler), and caching a page that contains a token so the next visitor receives a used one. Both fail with the duplicate error, and the fix is in the site's code, not the visitor's browser.

Why it loops

A loop means the widget keeps restarting instead of finishing. Cloudflare's client-side error codes and its challenge solve issues page together cover most causes. They fall into four groups.

The last group is the one people searching for help usually have, and Cloudflare's wording for it is short: if Turnstile suspects bot-like behavior, you may see repeated challenges. In our diagnosis work, the common triggers for real people are a privacy extension that alters browser APIs, a browser that is several versions out of date, a VPN or proxy exit with a poor reputation, and a WebRTC or time zone signal that contradicts the IP's location. For automated browsers, the triggers are the automation itself: navigator.webdriver, headless rendering differences and request patterns.

Fixes by cause

Work through these in order. Each step removes one group from the table above.

1. Confirm it is not the site. Open the same page in a second, clean browser on another network. If it loops everywhere, the site has a configuration error (the 110 and 400 codes) and only the site owner can fix it. Send them the code and the time.
2. Fix the clock. Turn on automatic date and time on the device. A clock that is minutes off produces 110600 and 200100 errors that look random.
3. Remove interference. Disable extensions, open a private window, and allow challenges.cloudflare.com in any content blocker, DNS filter or corporate proxy. In mobile apps, the WebView must allow that domain and run JavaScript.
4. Update the browser. Turnstile supports all major browsers except Internet Explorer, but an outdated build is both a compatibility risk and an unusual signal.
5. Check the network. If the loop appears only on a VPN or proxy, the exit is part of the problem. Run the WebRTC leak test and the DNS leak test to make sure the browser is not reporting a second location, and check the address type with the IP reputation check. Cloudflare itself suggests switching networks, for example to a mobile hotspot, to test this. If you route through a proxy on purpose, use one whose exit you control and do not share; Coronium's mobile proxies are dedicated carrier lines, one customer per device.
6. Keep one session on one address. A browser that changes IP between loading the widget and submitting the form presents a token minted for a different connection context. If you rotate IPs, do it between sessions.

For Cloudflare blocks that are not Turnstile (error 1020, 1015 rate limiting, full-page challenges), our Cloudflare IP ban check explains how to read the Ray ID and which errors a visitor can resolve.

If you are running an AI agent or automated browser that keeps meeting Turnstile, the issue is identity, not configuration. See why AI agents get blocked for the verified-agent route.

Site owners and visitors

If you run the site

• Validate every token server-side, once, and check hostname and action when your flow uses them.
• Do not cache pages or API responses that embed a token.
• Turn on pre-clearance if you also use WAF challenges. The pre-clearance guide explains how a solved widget can issue a cf_clearance cookie at an interactive, managed or non-interactive level, so the visitor is not challenged twice. The widget's hostname must match the zone, and the cookie lasts as long as the zone's challenge passage setting.
• In staging and automated tests, swap in Cloudflare's test sitekeys and test secrets. They return a dummy token, XXXX.DUMMY.TOKEN.XXXX, that only test secrets accept, so your end-to-end tests pass without anyone solving a challenge. Production secrets reject the dummy token, which keeps the shortcut out of production.
• Use the managed mode unless you have a reason not to. It asks for interaction only when Cloudflare is unsure.

If you are the visitor

You cannot change the site's configuration, and you do not need to defeat anything. A working, current browser with a correct clock, no interfering extensions and an honest network connection passes Turnstile in the normal case. If it does not, send the site owner the error code shown in the widget; the 110 and 400 families are theirs to fix.

If you automate someone else's site

Turnstile exists so the site owner can decide who gets through. Solver services and token farms move the problem without solving it and usually breach the site's terms. If the data matters to your business, ask the owner for an API or a test environment, or verify your agent through Cloudflare's bot program.

Frequently asked questions