Troubleshooting

Find what’s wrong and get your form working again. Each section starts from what you see, shows how to check it, and gives the fix. Formerie returns stable codes, and this page uses their exact names.

The sections:

• My Email Didn’t Arrive
• A Submission Was Rejected
• The Form Isn’t Showing
• A CORS Or Origin Error
• Verification Failed

My Email Didn’t Arrive

Symptom: someone filled in the form, and the email never showed up.

How to check: open Deliveries in the app and find the response by form and date. Each row has a status, and a diagnostic with a code, a summary, and a next step. The same details are on the response itself under Submissions. Then find what you see in this table.

Delivery Diagnostic Codes

Delivered, But Not In The Inbox

Delivered means the provider took the email. It doesn’t prove it reached the inbox.

1. Ask the recipient to check their spam folder.
2. If you use your own email provider, search its logs for the message.
3. Open the form’s Delivery tab, and make sure that address is on the form.
4. Open Recipients, and look at that address. A Pending, Disabled, or Suppressed recipient gets nothing. A suppressed address usually bounced or marked a message as spam.

Only Some People Got It

A recipient with a condition only gets the responses that match it. Compare the condition on the Delivery tab with the answers in the response. If a condition leaves nobody to send to, the response is kept and no email goes out, and that isn’t counted as a failure.

Retry A Delivery

Fix the cause first, because most failures repeat otherwise. Then open the response under Submissions and choose Retry delivery. It sends real email with the form’s current delivery settings, and doesn’t change the response.

A Test Email Won’t Send

A Submission Was Rejected

Symptom: the visitor sees an error, or your code gets ok: false.

How to check: a refused submission isn’t stored, so it never appears under Submissions. Read the code in the response instead, in your browser’s network panel or from result.error.code in the SDK. It looks like this:

{
  "ok": false,
  "error": {
    "code": "SPAM_REJECTED",
    "message": "The submission was rejected."
  }
}

The server runs its checks in order and stops at the first one that fails: origin, availability, rate limit on public routes, response window, size, format, repeat send, submission limits, spam checks, human verification, answers, and quota.

Failed Answers

VALIDATION_FAILED lists each problem in error.fields and error.issues, with a path, a code, and a message:

{
  "ok": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "The submitted form contains invalid fields.",
    "fields": {
      "contact.email": [
        {
          "path": "contact.email",
          "code": "FIELD_EMAIL_INVALID",
          "message": "Invalid email address.",
          "rule": "email",
          "params": {}
        }
      ]
    },
    "issues": [
      {
        "path": "contact.email",
        "code": "FIELD_EMAIL_INVALID",
        "message": "Invalid email address.",
        "rule": "email",
        "params": {}
      }
    ]
  }
}

Show each message next to its field. Hosted pages and embeds do this for you. The codes are listed by field type in the Form Definition Reference, and your own validators return the code you gave them.

A field that’s required but hidden can’t fail, because the server skips hidden fields. If a required field keeps failing, check that your own UI sends it under the exact name, with groups as nested objects.

Rejected As Spam

The response doesn’t say which check caught it, so go through all three under Settings, in Anti-spam:

Too Many Submissions

RATE_LIMITED comes from one of two places:

• Submission limits, under Settings. New forms allow 10 submissions per visitor every 10 minutes, and 300 for the whole form every hour. Raise them if your form gets real bursts. People on the same network, such as an office, share the per-visitor limit.
• A short-term limit on public routes, which you can’t change. It sends Retry-After, in seconds.

Tell the visitor to wait, and keep their answers on screen.

Repeat Sends

DUPLICATE_SUBMISSION means the first send already worked, and that’s good news. Show your success message. Send a new metadata.idempotencyKey for each new submission, and reuse a key only to retry the same one.

The Form Isn’t Showing

Symptom: the link shows an error, or the page where you embedded the form is blank.

How to check: open the form’s Hosted URL in a private window. If it works there, the form is fine and the problem is in the page around it. If you see a line of JSON, read its code.

An Embed Shows Nothing

• The script adds its iframe right where the tag sits. With data-formerie-target, the selector has to match something on the page when the script runs.
• data-formerie-form must be workspace-handle/form-handle, as in the Embed code. A wrong value shows FORM_NOT_FOUND inside the iframe.
• If your site sets a Content Security Policy, allow https://forms.formerie.com as a frame and script source, and https://cdn.formerie.com as a script source.

A Browser Mount Shows Nothing

The browser mount loads the form with a call from your page. Without your site’s address in the allowed origins, that call fails. See the next section.

A CORS Or Origin Error

Symptom: your browser’s console shows blocked by CORS policy, your code gets a network error such as Failed to fetch or the SDK’s NETWORK_ERROR, and the request shows as 403 or 404 in the network panel. Your code doesn’t get to read a Formerie code, because a refused browser request comes back without the headers that would let it.

How to check: this only happens when browser code on your own site calls Formerie, which means the browser mount, a framework package used in the browser, or your own fetch. A hosted link and a script embed don’t call from your site, so they can’t cause it.

Open the failed request in the network panel. It’s often the OPTIONS one, and its response says FORBIDDEN_ORIGIN or FORM_NOT_FOUND. Compare the request’s Origin header with your list.

Code on your own server doesn’t need any of this, unless it forwards an Origin header. Without one, the check doesn’t apply. See Allowed Origins.

Verification Failed

Symptom: a submission returns TURNSTILE_FAILED. It’s the same code for Cloudflare Turnstile and for reCAPTCHA, and the response doesn’t give a reason.

How to check: look at the form’s Human verification settings under Settings, then go through these causes.

Which Domain To Add To Your Widget

With your own keys, the provider’s console lists the domains your widget works on. Add the domain the widget loads on:

Verification Through Your Own Server

A token from your page, sent on through your own server, can fail on the domain check. Without an Origin header, Formerie compares the token’s domain with its own. To pass, forward the visitor’s Origin header with the request, and list that site under allowed origins too.