Troubleshooting

Submission returns 422 — validation error

Symptom: Submitting the form shows a validation error or returns HTTP 422.

Causes and fixes:

Error message	Cause	Fix
`"Email is required"`	Email was left blank	Fill in the email field
`"A valid email is required"`	Email present but malformed	Use a properly formatted address (e.g. `[email protected]`)
`"[Field] is required"`	A required field was left blank	Fill in the field

Submission returns 429 — too many requests

Symptom: HTTP 429 with { "errors": ["Too many requests. Please slow down."] }.

Cause: More than 10 submissions from the same IP address within a 5-minute window.

Fixes:

Wait 5 minutes and retry
If you're running automated tests, point them at a test environment rather than production
If you're doing a bulk import, use the Contacts API instead of the form endpoint

Submission returns 404

Symptom: HTTP 404 or the 404 page is returned.

Cause: The form token in the URL doesn't match any form in the system.

Fixes:

Double-check the token in your URL against the token shown in Embed
Ensure you haven't deleted the form
Tokens are case-sensitive

Contact not created after submission

Symptom: The API returns { "success": true } but no contact appears in your Contacts list.

Causes and fixes:

Email already exists — Taildove upserts by email. The contact was updated, not created. Search for the email in your Contacts list.
Double opt-in is on — The contact is created with subscribed: false and won't appear in your normal filtered views until they confirm. Check Contacts with the "Unconfirmed" filter.
Wrong account — Make sure you're logged into the same account that owns the form.

`maps_to` value is rejected when saving the form

Symptom: Saving the form shows a validation error on a field's Maps to value.

Rules for valid Maps to keys:

Lowercase letters, numbers, and underscores only
Must start with a letter (not a number or underscore)
Max 63 characters
Must be unique within the form

Examples:

✓ first_name, phone, company_name, cf_industry
✗ First Name (spaces not allowed)
✗ 1field (cannot start with a number)
✗ my-field (hyphens not allowed)

redirect_url is rejected when saving the form

Symptom: Saving the form shows "must start with http:// or https://" on the Redirect URL field.

Fix: Use a full absolute URL:

https://yoursite.com/thank-you   ✓
/thank-you                        ✗  (relative paths not allowed)
yoursite.com/thank-you            ✗  (must include the scheme)

Embed shows the wrong form or an old version

Symptom: An embedded form shows stale content after you edited it.

Cause: The HTML snippet is a static copy — it does not update automatically when you edit your form.

Fix: Copy a fresh snippet from Embed → HTML snippet and replace it on your site.

Double opt-in confirmation email is not arriving

Symptom: The contact is created but the confirmation email never arrives.

Checks:

Check your spam/junk folder
Verify your sending domain is set up correctly in Settings → Sending domains
Confirm the contact was created with subscribed: false (look at the contact record)
Check Settings → Email Templates to ensure the confirmation email template is active