Headless spam protection and limits
Headless submissions support a honeypot field, optional Turnstile checks, and rate limiting. Use these controls to protect a Headless form and understand its plan limits.
Beta
This feature is available to all accounts. Its request and response format can change without a new API version. Do not depend on it for anything you cannot update quickly.
Honeypot field
The honeypot field is named _gotcha. It is enabled by default when spam_mode is honeypot. Set spam_mode to none to turn it off. The optional embed.js script adds a hidden _gotcha input if the form does not already have one.
Turnstile
You can require Cloudflare Turnstile for a Headless endpoint. Set it up in the dashboard with a site key and secret.
Browser submissions must include the Turnstile token as cf-turnstile-response or _turnstile. A missing or failed token returns 400 with code captcha. Submissions using a backend key skip Turnstile.
CAPTCHA is a form setting, not a field. You can configure the captcha setting with { "enabled": true, "provider": "turnstile" } through the MCP update_form_settings tool. A Page form with hosted CAPTCHA enabled rejects Headless submissions with 403 and code captcha.
Rate limits
Requests can be rate limited. The response is 429 with retryAfter. Back off by that value.
Plan limits
| Free | Pro and Business | |
|---|---|---|
| Enabled endpoints | 1 | Unlimited |
| Headless submissions per month | 50 | Unlimited |
| Respondent auto-reply | No | Yes |
| Respondent email verification | No | Business only |
Each form can have only one endpoint. Enabling an endpoint requires at least one allowed origin or a backend API key; otherwise, the request returns 400. Enabling a second endpoint on Free returns 403. Team forms are billed to the team owner.
When the monthly submission quota is reached, the submission returns 429 with code quota. Its retryAfter value is the number of seconds until the next UTC month.
Submission limits
The request body limit is 256 KB. A larger body returns 413:
{
"ok": false,
"error": "Payload is too large",
"code": "validation"
}File uploads are not supported. Unsupported content types, including multipart/form-data, return 415 with code unsupported.
Respondent email verification
Respondent email verification is available on Business plans. It supports at most five verified fields and browser submissions only. While any field requires verification, a submission using a backend key returns 403 with code email_verification.