> ## Documentation Index
> Fetch the complete documentation index at: https://formpaste.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting & FAQ

> Common issues, what's actually happening, and how to fix them.

Fixes for the issues that come up most, each mapped to the real error code or behavior
behind it. For the complete code list, see the [error reference](/docs/reference/error-table).

## "I'm not receiving email for submissions"

Almost always one of these, in order of likelihood:

1. **The destination email isn't verified yet.** A new form's destination holds all
   delivery until you enter the 6-digit code Formpaste emailed to it. Check the form's
   Setup tab in the [dashboard](https://app.formpaste.com) for a "pending
   verification" state. See [Your first form](/docs/first-form#verify-the-destination-email).
2. **The submission landed in quarantine, not the inbox.** Quarantined submissions are
   never emailed - that's the point of [quarantine](/docs/features/quarantine). Check the
   form's **Spam** tab; if it's there, see the quarantine section below.
3. **You're over your monthly quota.** Once a plan's submission cap is crossed for the
   billing month, further submissions are accepted and stored but held rather than
   emailed until the month rolls over or you upgrade. See
   [Free plan limits](/docs/features/free-plan-limits).
4. **Check spam/junk in your actual mailbox** - outside Formpaste's control, but the
   most common false alarm.

## "403 domain\_not\_allowed"

The submitting page's origin isn't on this form's allowlist. Open the form's Setup tab →
**Allowed domains** and add the domain the form is served from (e.g. `example.com` for
`https://example.com/contact`). If the allowlist is empty, every origin is accepted - so
this only fires once you've locked a form down. See
[Domain allowlist](/docs/features/custom-domains).

## "401 invalid\_access\_key"

The `access_key` field either wasn't sent, doesn't match any form, or belongs to a form
that's been deleted. Re-copy the key from the form's Setup tab in the dashboard (or call
[`get_snippet`](/docs/agents/get-snippet) with the `formId` to get a snippet with the real
key filled in) and make sure it's the value of an `access_key` field in the request body
— not an `Authorization` header. `/submit` doesn't accept Bearer auth; that's only for
the [MCP server](/docs/agents/mcp-server).

## "My submission was quarantined"

Formpaste scores every submission with spam heuristics (honeypot, timing, link
density, rate, disposable/duplicate email) and routes anything suspicious to the
**Spam** tab instead of dropping it - see [Spam filtering](/docs/features/spam-filtering)
for what's checked. Common causes of a false positive:

* The `botcheck` honeypot field was accidentally given a real `value`, or your CSS hides
  it in a way a browser autofill/extension can still populate.
* The form was submitted faster than `_ts` suggests a human could fill it - common in
  automated testing; not usually a false positive in production traffic.
* The submitted `email` is on a disposable-provider domain and
  `allow_disposable_email` is off for this form.

You can see quarantined submissions on Free (read-only). Re-delivering one ("not spam")
requires [Pro's rescue action](/docs/features/quarantine-rescue) - on Free, remove the cause
(fix the honeypot wiring, or turn on `allow_disposable_email`) and have the visitor
resubmit.

## "400 missing\_access\_key / invalid\_body"

`missing_access_key` means no `access_key` field was present at all - check the input
name is exactly `access_key`, not a typo, and that it's actually inside the `<form>` (or
`FormData`/JSON body) being sent. `invalid_body` means the request body couldn't be
parsed as JSON or form data - check `Content-Type` matches what you're actually sending
(`application/json` for a JSON body, left to the browser default for a plain HTML form
or `FormData`).

## "400 invalid\_redirect"

The `redirect` field's URL isn't on this form's allowed-domains list. Either add that
domain to **Allowed domains**, or remove the `redirect` field if you're submitting via
`fetch`/AJAX and don't need a page navigation. See [Redirects](/docs/features/redirects).

## "403 upgrade\_required"

You're on Free and tried to use or configure a Pro-only capability: quarantine rescue,
autoresponder, additional/CC recipients, webhooks, or file uploads. See
[Free plan limits](/docs/features/free-plan-limits) for the full list, or
[Pro plan](/docs/features/pro-plan) to upgrade.

## "429 rate\_limited"

Too many submissions from the same source in a short window. This is independent of
content - it fires even on legitimate traffic if it's bursty. Slow down retry logic
(exponential backoff, not a tight loop) and it clears on its own.

## "My webhook isn't firing"

Webhooks only fire for delivered, non-spam submissions - a quarantined submission never
triggers one. Confirm `webhook_url` is set and Pro is active on the account, check the
dashboard's per-form delivery log for failed attempts, and confirm your endpoint is
`https://` and returns a `2xx` quickly. See [Webhooks](/docs/features/webhooks) for retry
timing and the signature-verification recipe.

## "Do I need a CAPTCHA?"

No - Formpaste is designed specifically so you don't add one. Spam is caught with the
`botcheck` honeypot, `_ts` timing, and server-side heuristics instead. See
[Preventing spam](/docs/guides/preventing-spam).

## "Is there a REST API for submissions/forms?"

No. Forms are created in the dashboard or via the MCP
[`create_form`](/docs/agents/create-form) tool; submissions are read via the dashboard, CSV
export, or the MCP [`list_submissions`](/docs/agents/list-submissions) tool. See
[Retrieving submissions](/docs/reference/submissions-api) for the full breakdown - there is
no `GET`/`POST` REST API for forms or submissions beyond `POST /submit` itself.

<CardGroup cols={2}>
  <Card title="Error reference" icon="triangle-exclamation" href="/docs/reference/error-table">
    Every code, its HTTP status, and its message.
  </Card>

  <Card title="Options reference" icon="sliders" href="/docs/reference/options">
    The reserved fields and dashboard config these errors relate to.
  </Card>
</CardGroup>