Troubleshooting and FAQ

Start here when something does not work. Error names are in error codes.

Verification fails

success is false and error-codes has timeout-or-duplicate. A token lives 300 seconds and verifies once. Common causes: you verified the same token twice (for example once in middleware and once in the handler), the person waited too long on the form, or a retry reused a spent token. Verify exactly once, and ask the widget for a new token after any failure.

invalid-input-secret. You sent the wrong key, a public site key (rgpk_...) instead of the secret (rgsk_...), or a management key (rgmk_...). Check the environment variable and that production uses the production site’s secret.

sitekey-secret-mismatch. The page uses the site key of one site and your server the secret of another. Use the pair from the same site.

bad-request. Siteverify was called from a browser (a request with an Origin header), the secret was sent twice (body and Bearer), the body was not form or JSON, or you sent an unknown field to /v1/siteverify.

The SDK says hostname-mismatch. The token was issued for a page on another hostname than expectedHostname. Hostnames are compared exactly: lowercase, no port, no trailing dot. Add every hostname you use to the site in the dashboard.

The SDK says threshold-missing. You did not pass minScore. Always pass it (0.5 is a good start for web).

The SDK says action-mismatch. The action in the token is not the one you expect. Use the same action string in the client and in expectedAction (letters, digits, / and _, up to 100 characters).

Check that the page’s hostname is on the site’s hostname list (hostname-not-allowed), and that the site key is the public rgpk_ key (invalid-site-key).
Check the browser console. A strict Content-Security-Policy must allow the widget script and frame from the RevokeGPT hosts.
On mobile, app-not-allowed means the package name or bundle id is not on the site’s app list.
A privacy browser or tool may lower a score but never blocks a person on its own: see privacy tools.

Scores look wrong

Local development and tests often score low (automation, headless browsers, datacenter addresses). Use a test site, and read reasons: see scores and reasons.
Behind a proxy, pass the real client address as remoteip, not the proxy’s. Otherwise every visitor looks like one datacenter address (DATACENTER_IP, TOO_MUCH_TRAFFIC).
Token and verification should happen close in time. A NETWORK_MISMATCH reason (score capped at 0.3) means the network at solve time differs from the network at check time.

Plan and billing

plan-required or plan-restricted (HTTP 402 or a siteverify error code): the organization has no active plan or it is restricted. Check billing and spend cap.
quota-exceeded: the included checks are used up and the spend cap does not allow more.
A restricted plan gets pass-through checks without scoring, with the reason PLAN_RESTRICTED.

Assessments and features

403 feature-disabled: the feature (assessments, account protection, MFA, payment or SMS scoring, credential pair) is not enabled for the site.
401 unauthorized: the secret is missing, wrong, a management key, or the site is disabled. It is one uniform answer on purpose.
503 service-unavailable: assessments or the feature are off or unavailable. Siteverify is unaffected, so you can fall back to it.
429 rate-limited: wait for the Retry-After seconds (1) and retry once.

Firewall

Nothing is blocked: check that the rule is enabled, the host and path match (case-sensitive), the method is listed (* does not match OPTIONS), and the kill switch is off.
Everything passes with X-RG-Verdict: none: the integration has not verified a bundle yet and its initial fail mode is open. Check the pinned keys and the site key.

FAQ

Is a score of 1.0 the human or the bot? 1.0 is human, 0.0 is bot, in steps of 0.1.

Can I verify in the browser? No. Verification is server to server. A browser request is refused.

How long does a token last, and can I check it twice? 300 seconds, and once.

What should I do when the service is down? Decide in advance. For low-risk forms you may fail open; for payments and logins fail closed or fall back to another check. Never treat an error as success.

Do you send SMS? No. Email codes only. See email MFA.

Is the password sent to you in the password check? No. Only the first 5 hex characters of its SHA-1 hash. See password check.

Can I migrate from reCAPTCHA? Yes. The path /recaptcha/api/siteverify is compatible. See migrate from reCAPTCHA v3, v2 and Enterprise.

Is a package missing on npm, PyPI or another registry? Some SDKs are not published yet; the quickstart and the SDK reference say so on each page.

How do I report a vulnerability? See security and privacy.

If none of this helps, include the requestId from an error body when you contact support. It never contains secrets.