A Cloudflare Turnstile-protected sign-up endpoint rejects some genuine users because siteverify returns timeout-or-duplicate; what causes it, and how do you fix it?
answer
- one token, one validation
- a second verifier downstream
- resubmitting after a form error
- idempotency_key for retries
- reset the widget each time
basics
~20 stimeout-or-duplicate means the token was already validated or outlived its 300 seconds: a second verifier, a retried request, a resubmitted form or a stale copy. Validate each token once, retry siteverify with an idempotency_key, and reset the widget before resubmitting.
solid answer
~50 sA Turnstile token is valid for 300 seconds and can be validated **once**; a second siteverify call for it returns `timeout-or-duplicate`, the code Cloudflare also reports for a token submitted after its lifetime. Genuine users hit it when the system spends one token twice: an edge Worker verifies and the origin verifies again, a middleware and a handler both call siteverify, a client retries a timed-out POST with the same body, or the form re-renders after a server-side error (such as an email already in use) and resubmits the spent token. Fix it by verifying in exactly one place and passing the verdict downstream, adding an `idempotency_key` UUID when retrying the siteverify call itself, calling `turnstile.reset(widgetId)` after every submission, and reading the token at submit time with `turnstile.getResponse()` rather than caching it. Never treat the error as a pass.
code
javascript · 17 lines// Explicit rendering in a single-page sign-up form.
const widgetId = turnstile.render("#turnstile-container", {
sitekey: "<YOUR-SITE-KEY>",
action: "signup",
});
async function submitSignup(form) {
const token = turnstile.getResponse(widgetId); // read at submit time
const body = new FormData(form);
body.set("cf-turnstile-response", token ?? "");
try {
const res = await fetch("/signup", { method: "POST", body });
return res.ok;
} finally {
turnstile.reset(widgetId); // the token is spent either way
}
}go deeper
Recall that a Turnstile token works once and for 300 seconds, and that timeout-or-duplicate means it was already validated.
Explain how a genuine token fails: spent twice by double verifiers, retried POSTs or a form re-shown after an error, or expired as a stale copy in app state.
Trace the failing path from logged error codes, consolidate to one verifier, add idempotency keys and widget resets, and test the duplicate path with the dummy secret.
Decide where human verification lives in a multi-tier stack, how its verdict is trusted downstream, and how failures surface without weakening the single-use rule.
## What the error means **Siteverify** is the server-side half of Turnstile. Your backend sends the token from the widget, with the widget's secret key, to `https://challenges.cloudflare.com/turnstile/v0/siteverify`, and Cloudflare answers with `success` and, on failure, an `error-codes` array. Two token rules shape the answers: - a token is valid for **300 seconds** after the widget generated it; - a token can be validated **only once**; a replay is rejected with `timeout-or-duplicate`. The code name covers both failures: the error-code reference describes it as a token that has already been validated, and the token-lifetime notes report it for a token submitted after its five minutes. So when real users see `timeout-or-duplicate`, the question is how a token they solved once was presented to siteverify twice, or late. The error does not mean the visitor was a bot, and it is not fixed by loosening the check. | Error code | Usual cause on a sign-up form | | --- | --- | | `timeout-or-duplicate` | The token was already validated | | `invalid-input-response` | The token is malformed or not one Cloudflare issued | | `missing-input-response` | The form arrived without a token | | `invalid-input-secret` | The secret key is wrong, for example after a rotation was not deployed | ## How a genuine user's token fails Look for these patterns in the sign-up path; the first three spend one token twice, the last submits it late: - **Two verifiers.** An edge Worker validates the token and forwards the request, and the origin application validates it again. Or a framework middleware and the route handler both call siteverify. The second call always fails. - **Retried submissions.** A mobile network drops the response, the client retries the same POST with the same token, or a user double-clicks Submit. The first request spent the token even if its response was lost. - **Form errors.** The first submission validated the token and then failed for another reason, such as an email address already registered. The page re-displays the form with the old token still in `cf-turnstile-response`, and the second submission replays it. - **Stale copies.** A single-page app copies the token from the success callback into its own state. When the token expires, the widget's default `refresh-expired` behaviour (`auto`) fetches a fresh one, but the app still submits the stale copy. ## Fixing it 1. **Verify once.** Choose one tier, the edge or the origin, to call siteverify, and pass the result on, for example as an internal header set by the Worker on its subrequest to the origin, which the origin accepts only from the Worker. 2. **Make server retries safe.** If the siteverify call itself times out, retry with the same `idempotency_key`, a UUID you generate per validation, so the retry is not counted as a second use. 3. **Reset after every submission.** Whether the submission succeeded or failed, call `turnstile.reset(widgetId)` before the user can submit again, so a new token replaces the spent one. 4. **Read the token at submit time.** Use `turnstile.getResponse(widgetId)` when the form is sent, and handle `expired-callback` if you disable automatic refresh, instead of keeping your own copy. 5. **De-duplicate client retries.** Disable the submit button while a request is in flight, and when a retry fails with `timeout-or-duplicate`, ask for a fresh token rather than reporting a hard failure. ## Verifying the fix - Log the `error-codes` of every failed validation with the route and tier that made the call; a second call from the same request ID shows a double verifier at once. - Use the testing secret key `3x0000000000000000000000000000000AA`, which always returns a token-already-spent error, to exercise the duplicate path in automated tests, and the dummy sitekeys to drive the widget. - Watch Turnstile Analytics: token validations should track challenges solved, and a jump in failed validations after a deploy points to a new second verifier. ## What not to do Accepting `timeout-or-duplicate` as success, caching a validation verdict by token for later requests, or moving the check into the browser all reopen the replay the single-use rule exists to close. A replayed token is exactly what an automated sign-up campaign would send. Two adjacent shortcuts fail the same way. Raising the widget's retry settings does not help, because retries happen in the browser before a token exists, not at siteverify. Switching the widget to Invisible mode changes only what the visitor sees; the token it produces is still single-use and still expires after 300 seconds, so the double-verifier bug survives any mode change.
- What does idempotency_key on a Turnstile siteverify call protect against?It protects the server's own retries. If the siteverify request times out, the server cannot tell whether Cloudflare already validated the token; retrying with the same `idempotency_key`, a UUID generated per validation, lets it repeat the call safely, which is what the parameter is for. It does not make a token reusable across different submissions.
- After a Turnstile secret key rotation, sign-ups start failing with invalid-input-secret; what happened?Rotation keeps the old and new secret keys valid together for two hours. If some servers or Workers still carry the old key when that window closes, their siteverify calls fail with `invalid-input-secret`. Deploy the new key everywhere within the window, and alert on that error code, which never points at the visitor.
- timeout-or-duplicate proves the visitor is a bot, so the rejection is correct.
- Treat timeout-or-duplicate as success, since the token was valid once.
- Validating at both the edge and the origin doubles the protection.
- A token stays reusable for its full 300 seconds.
- Rotating the secret key immediately invalidates the old one.