Headless errors

Use this page to identify errors returned by Headless submission and email verification requests.

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.

Submission errors

Submission errors use a JSON body with ok: false, error, and code. Validation responses can also include errors, whose entries have field and message, and fieldErrors, which maps field names to messages. Partial-save validation errors include fieldErrors but no errors array. Some errors include retryAfter in seconds and a matching Retry-After header.

Status	Code	Meaning
400	`validation`	The submission failed form validation. In strict mode, an unknown field returns `Unknown field for this form`. File-upload fields fail validation because Headless uploads are unsupported. Page forms must use strict mode or the request returns 400. Check field errors and correct the answers.
400	`captcha`	A required Turnstile token is missing or failed validation.
400	`idempotency_key_invalid`	The idempotency key is invalid, or the header and body keys do not match.
401	`auth`	The backend API key is missing or invalid.
403	`auth`	The request origin is not allowed.
403	`captcha`	The form is a Page form with hosted CAPTCHA enabled, so it cannot accept Headless submissions.
403	`email_verification`	Email verification is required, but the submission used a backend key. The response uses `verificationCode: "EMAIL_VERIFICATION_REQUIRED"`.
403	`unsupported`	A partial save was sent to a Headless-only form.
404	`endpoint`	The endpoint is unknown, disabled, or unavailable. The submit URL requires the endpoint ID; using a form ID returns `{"ok":false,"error":"Endpoint not found","code":"endpoint"}`.
409	`idempotency_conflict`	The same idempotency key was used with a different request.
409	`schema_changed`	The schema was locked while a loose-mode request was in flight.
409	`email_verification`	The form’s verification settings changed after verification. The response uses `verificationCode: "VERIFICATION_POLICY_CHANGED"`.
413	`validation`	The request body exceeds 256 KB. Authentication is checked before size.
415	`unsupported`	The request uses an unsupported content type. `application/json` and `application/x-www-form-urlencoded` are accepted; `multipart/form-data` is unsupported.
422	`email_verification`	Verification proof is missing or invalid. No proof, malformed `_email_verification`, missing `_session_id`, or an expired or unknown receipt returns `verificationCode: "EMAIL_VERIFICATION_REQUIRED"`.
429	`rate`	The request was rate limited. Wait for the time in `retryAfter` before retrying.
429	`quota`	The plan’s monthly Headless submission limit was reached. `retryAfter` gives the seconds until the next UTC month.
500	`service`	An unexpected server error occurred. Retry later; an idempotency key makes a submission retry safe.
503	`service`	In loose mode, the schema could not be confirmed. Keep the answers and retry the same submission.
503	`idempotency_unavailable`	Idempotency is unavailable.
503	—	Schema learning is unavailable.

A form that is not published returns 400. A redirect URL that is not allowed also returns 400.

Idempotency keys

An idempotency key must be 8–128 characters and use letters, digits, ., _, :, or -. You can send it in the Idempotency-Key header or as _idempotency_key in the body. If you send both, they must match. A retry is safe when you reuse the same key with the same request.

Browser origin and backend key

An Origin header makes the request a browser request. If you include a backend key too, the key is ignored. The origin must be allowed for the endpoint.

Email verification submission errors

When verification proof is missing or invalid, the submission response includes code: "email_verification" and a verificationCode with the specific reason. It can also include fieldId, errors, and fieldErrors. If fieldId is absent, discard every stored receipt and verify again.

{
  "ok": false,
  "code": "email_verification",
  "error": "Verify the email address before submitting",
  "verificationCode": "EMAIL_VERIFICATION_REQUIRED",
  "fieldId": "FIELD_ID",
  "errors": [
    { "field": "email", "message": "EMAIL_VERIFICATION_REQUIRED" }
  ],
  "fieldErrors": {
    "email": "EMAIL_VERIFICATION_REQUIRED"
  }
}

Email verification errors

Most email verification endpoint errors include success: false, code, and error. They can include fieldId and retryAfter; when retryAfter is present, it is in seconds and is also sent in the Retry-After header. A 500 server error instead returns {"ok":false,"error":"Server error","code":"service"}.

Status	Code	Meaning
400 or 413	`validation`	The body is not a JSON object or exceeds 8 KB.
400	`INVALID_REQUEST`	`sessionId` is missing or too long.
400	`CODE_INVALID`	The code is wrong, or a required code, attempt secret, session ID, or challenge ID is missing or malformed.
403	`auth`	The request has no `Origin` header, or its origin is not allowed.
404	`endpoint`	The endpoint is unknown or disabled.
409	`VERIFICATION_POLICY_CHANGED`	The field is not a verified email field on the published form, or the form’s verification setup changed. Drop stored field IDs and start again using `field`.
409	`UNSUPPORTED_VERIFICATION_POLICY`	The form’s verification setup is invalid.
410	`CODE_EXPIRED`	The code is too old. Request a new one.
415	`unsupported`	The request content type is not JSON.
422	`EMAIL_RISK_BLOCKED`	The address was rejected; no code was sent.
422	`VERIFICATION_VALUE_CHANGED`	The address, session, or origin differs from the one used to request the code.
423	`CODE_LOCKED`	Too many incorrect codes were entered. Request a new code.
429	`RESEND_TOO_SOON`, `RATE_LIMITED`	It is too soon to request another code, or the request was rate limited. Wait for `retryAfter`.
429	`rate`	The request was rate limited. Wait for `retryAfter`.
500	`service`	A server error occurred.
503	`DELIVERY_UNAVAILABLE`, `VERIFICATION_UNAVAILABLE`	The email could not be sent, the form is closed, or the service is unavailable. Retry later.