Error codes

The error envelope

When a request is made in JSON mode (see the submit reference), an error returns the HTTP status from the table below and this body:

{
  "error": "<code>",
  "message": "Human-readable explanation.",
  "fieldErrors": { "email": "..." }
}

• error — the stable code, one of the values below. Branch on this, not on the message text.
• message — a human-readable explanation. Wording may change; do not parse it.
• fieldErrors — present only when specific fields failed validation; maps each field name to a reason.

HTML form redirects

A traditional HTML form post does not receive the JSON envelope. Instead, when the form has an error URL configured, the visitor is redirected to it with the code appended as a query parameter:

HTTP/1.1 303 See Other
Location: https://example.com/error?error=quota_exceeded

Read the ?error=CODE value on your error page to show a relevant message. To get the JSON envelope instead of a redirect, send Accept: application/json. See HTML installation for the redirect flow.

Errors a form submitter will hit

These are the codes most relevant when submitting a form. They cover a missing or disabled form, blocked origins, oversized or over-quota submissions, throttling, failed spam checks, and a form with nowhere to deliver.

Note that Turnstile and honeypot failures are usually handled silently for legitimate-looking traffic — see Spam protection for how filtered submissions are treated.

Full catalog

The complete set of codes the API can return, including account, authentication, and billing errors surfaced through the dashboard.

Related

• Submit API reference — the endpoint, headers, and response shapes.
• Spam protection — honeypot and Turnstile behavior.
• FAQ — common questions and troubleshooting.