All docs
6 min read

Common issues

In rough order of how often they show up in support tickets.

1. 401 on POST to /f/{public_id}

Symptom. You're submitting from your frontend and getting 401.

Cause. Almost always: you're hitting the API path (/api/v1/...) instead of the submission path (/f/...). Submission endpoints don't take an Authorization header — they're public by design. The API does, and the wrong path returns 401 because no token was provided.

Fix. POST to https://formspring.io/f/{public_id} (the submission endpoint), not /api/v1/forms/{public_id}/submissions. The latter exists but is for authenticated server-to-server use, not browsers.

2. CORS denials

Symptom. Browser console shows CORS policy: No 'Access-Control-Allow-Origin'.

Cause. The form has allowed_origins configured and your site's origin isn't in the list. Or you're submitting from a file:// URL (always denied).

Fix. Open the form → Settings → Origins. Add the origin. Wildcards aren't allowed by default; specific scheme + host + port match required. For local dev: add http://localhost:5173 (or whichever port). For production: add the production origin.

If you want the form to accept submissions from anywhere, leave allowed_origins empty. We don't auto-allow * unless you do that explicitly.

3. Files not arriving in webhooks

Symptom. Submissions with file uploads land in the dashboard fine, but the webhook payload's file fields are empty or contain only metadata.

Cause. Webhooks deliver a JSON payload. Files don't fit in JSON — what we send is a signed URL you can fetch the file from, not the file bytes.

Fix. In your webhook handler:

const { files } = req.body;
for (const file of files) {
  const response = await fetch(file.url);
  const bytes = await response.arrayBuffer();
  // ...store, scan, do whatever
}

The signed URLs are valid for 15 minutes after the webhook fires. If your handler is async and might not get to the file in time, store the URL+expiry and re-fetch via the API (get_submission_file) which mints a fresh signed URL on demand.

4. Autoresponder not firing

Symptom. Submissions land, no autoresponder reaches the submitter.

Causes (in order of frequency):

  1. Autoresponder is disabled. Check Form → Settings → Autoresponder. The toggle is at the top.
  2. Body is empty. Even if enabled, an empty template doesn't send.
  3. Form has no email field. We need to know the submitter's address. The autoresponder sends to whatever field is mapped as the "reply-to" in form settings, and if that field doesn't exist or is empty in the submission, no autoresponder is sent.
  4. Submitter's address is suppressed. Check the email activity log at Settings → Email → Activity. If the address bounced previously, the mail provider won't try again. See deliverability.
  5. Submission was flagged spam. Spam submissions don't trigger autoresponders by design. This is usually what you want.

5. Captcha invalid (422 captcha_invalid)

Symptom. Submissions fail with 422 and the error mentions captcha.

Causes:

  1. Site key mismatch. The hCaptcha or reCAPTCHA site key embedded in your frontend doesn't match what the form has configured. Check both.
  2. Token expired. hCaptcha tokens are valid for ~2 minutes after the user solves. If your form sits idle, the token expires.
  3. Token reused. Each token can only be used once. If you POST twice with the same token, the second call fails.
  4. Server-side environment. If you're testing from the server (not a browser), there's no real challenge — captcha will always fail. Disable captcha on the form for server-tested flows, or use the test site keys hCaptcha publishes for sandbox use.

6. redirect_url cross-origin breaks

Symptom. You set a redirect_url and submissions either don't redirect or land on a "redirect blocked" page.

Cause. When the form is hosted on Formspring (no custom embed), redirects work fine. When you've embedded the form on your own site and the redirect_url is on a different origin, the browser's CORS rules bite the redirect response.

Fix. Two options:

  1. Stay same-origin. Set redirect_url to a path on the same origin you're submitting from.
  2. Don't redirect server-side. Omit redirect_url, capture the success response client-side, and window.location from JavaScript. Works across origins.

The second pattern is what most embedded forms use in 2026.

7. Slug collisions on form creation

Symptom. Creating a form via the dashboard or API returns 409 slug_taken even though you didn't pick a slug.

Cause. Form public IDs are auto-generated, but the slug (used for hosted form URLs like formspring.io/contact) is derived from the form's name. If two forms have the same name, the second collides.

Fix. Either rename one, or pass an explicit slug when creating via the API: POST /api/v1/forms { name: "Contact", slug: "support-contact" }. Slugs must be unique across your team only — not globally.

8. AI insights "locked"

Symptom. AI insights tab shows "Locked — upgrade to unlock" but you're on Pro+.

Cause. Either (a) the team's plan really doesn't include insights — Free does not — or (b) the form has fewer than 50 submissions. AI insights need a minimum corpus to be meaningful.

Fix. Confirm the plan at Billing. If on Pro+ and the form has <50 submissions, wait — insights start generating automatically once the threshold's crossed. To force a regeneration after, use the MCP regenerate_ai_insights tool or the dashboard's Regenerate button (Pro+ only, 5-minute idempotency lock).

9. Webhook deliveries failing silently

Symptom. No errors in the dashboard but your endpoint isn't being hit.

Causes:

  1. Webhook is inactive. Check the toggle on the webhook detail page.
  2. Form has no submissions arriving in the inbox. Webhooks fire on inbox additions only. Spam-flagged submissions don't trigger webhooks unless you've explicitly enabled "fire on spam" (off by default).
  3. Endpoint returning 5xx for hours. After repeated failures we mark the webhook failed and stop attempting. Check the deliveries log on the webhook detail page; if every recent attempt is red, your endpoint is the issue, not us. Replay any delivery once you've fixed the endpoint.

10. "Form archived" 410 errors

Symptom. A form was working and now returns 410.

Cause. Someone archived it. Archive is soft-delete — it preserves the form but stops accepting submissions.

Fix. Open Forms → Archived, find the form, click Restore. The public ID is unchanged; existing integrations resume working immediately.

Still stuck?

  • Check HTTP errors for the full status-code table
  • Read the deliverability doc if it's email-related
  • Inspect the email activity log and webhook deliveries log — both are the fastest ground-truth view we have

If none of those help, email info@pixelandprocess.de with the form's public ID and the timestamp of a failing attempt. We can usually pinpoint the issue from the request log within an hour during business hours.

What's next

← Previous
Rate limits