Docs / Reference
Error codes
When the endpoint rejects a submission, nothing is stored. Each error has a stable code, listed here.
{
"ok": false,
"error": {
"code": "rate_limited",
"message": "Too many messages. Please wait a minute and try again.",
"docs": "https://wrenform.com/docs/errors#rate_limited"
}
}In JSON mode you get this object with the matching HTTP status. In browser mode the visitor sees a hosted error page with the same status and message. Each JSON error links to its section below.
Codes are stable; messages may change, so branch on code. Every response carries an X-Request-Id header: include it if you write to us. A 429 also carries Retry-After, in seconds.
Codes
form_not_found
HTTP 404. Message: "This form doesn't exist or has been deleted."
- What happened: The form ID in the URL doesn't exist, or the form was deleted.
- What to do: Copy the endpoint again from the form's Setup page in your dashboard.
form_paused
HTTP 403. Message: "This form isn't accepting messages right now."
- What happened: The form's owner paused it.
- What to do: Resume the form in its settings.
form_suspended
HTTP 410. Message: "This form has been suspended."
- What happened: The form was suspended under the acceptable-use policy.
- What to do: If you think this is a mistake, reply to the suspension email or write to abuse [at] wrenform.com.
origin_not_allowed
HTTP 403. Message: "This form doesn't accept messages from this website."
- What happened: The page that posted isn't in the form's allowed origins, or the request came from a local file or a sandboxed frame (we always reject those). With allowed origins set, a page whose
Referrer-Policyisno-referrerorsame-originalso fails: the browser then hides which site sent the form. - What to do: Add your site's origin (for example https://example.com) to the form's allowed origins, and test from the live site, not a file on disk. If you set allowed origins, keep the browser default
Referrer-Policy(strict-origin-when-cross-origin) on the form's page, or add<meta name="referrer" content="strict-origin-when-cross-origin">to that page's head.
payload_too_large
HTTP 413. Message: "The message is too large."
- What happened: The request body is over 64 KB.
- What to do: Send less text. File uploads aren't supported yet.
too_many_fields
HTTP 422. Message: "The form has too many fields."
- What happened: The form sent more than 100 fields.
- What to do: Reduce the number of fields, or combine related ones.
field_too_long
HTTP 422. Message: "One of the fields is too long."
- What happened: A field name is over 100 characters, or a value is over 10,000 characters.
- What to do: Shorten the field name, or add a maxlength to the input.
unsupported_media_type
HTTP 415. Message: "The form was sent in a format we can't read."
- What happened: The Content-Type isn't one we accept.
- What to do: Send application/x-www-form-urlencoded, multipart/form-data or application/json.
invalid_json
HTTP 422. Message: "The JSON body is invalid or nested."
- What happened: The JSON body is malformed, or contains a nested object.
- What to do: Send a flat object of strings, numbers, booleans or arrays of strings.
empty_submission
HTTP 422. Message: "The form was empty."
- What happened: No data field had a value.
- What to do: Check that your inputs have name attributes; fields without a name aren't sent.
rate_limited
HTTP 429. Message: "Too many messages. Please wait a minute and try again."
- What happened: Too many submissions from one visitor or to one form in a short time.
- What to do: Wait for the number of seconds in the Retry-After header, then try again.
quota_exceeded
HTTP 429. Message: "This form can't accept more messages this month."
- What happened: The account reached three times its monthly quota, our abuse ceiling.
- What to do: Upgrade the plan, or wait for the next month. Up to that ceiling, submissions over quota are stored, just not emailed.
form_pending_confirmation
HTTP 429. Message: "This form is waiting for its owner to confirm it, and can't take more messages until then."
- What happened: The form was created without an account and its recipient hasn't confirmed yet. Until then it holds at most 10 messages an hour and 50 in all.
- What to do: Ask the recipient to click Confirm in the email from Wrenform. The held messages are delivered then.
internal_error
HTTP 500. Message: "Something went wrong on our side."
- What happened: Something went wrong on our side. It's logged with the request ID.
- What to do: Try again in a moment. If it keeps happening, email hello [at] wrenform.com with the X-Request-Id header.
REST API and AI tool codes
These come from the REST API and the MCP server, in the same { ok, error } shape (AI tools
get the message and the fix as text). rate_limited and internal_error mean the same as above.
unauthenticated
HTTP 401.
- What happened: The API key or AI tool connection is missing, wrong, revoked or expired.
- What to do: Send Authorization: Bearer with a valid wf_live_ key, or connect the AI tool again so it signs in.
forbidden
HTTP 403.
- What happened: This credential may not do that, for example an action that stays in the dashboard.
- What to do: Do it in the dashboard instead.
insufficient_scope
HTTP 403.
- What happened: The key or connection doesn't have the permission (scope) this call needs. The error names it.
- What to do: Create a key with that scope, or connect the AI tool again and tick the permission.
not_found
HTTP 404.
- What happened: No form, submission or webhook with that ID in this account.
- What to do: List the account's forms (GET /api/v1/forms or the list_forms tool) to find the right ID.
conflict
HTTP 409.
- What happened: The change clashes with the form's current state, for example deleting a form that is under review.
- What to do: Read the error message: it says what's blocking the change. Wait for the review to finish, or contact us.
validation_failed
HTTP 422.
- What happened: The request body or arguments are invalid. error.fields names each field and what's wrong.
- What to do: Fix the named fields and send the request again.
plan_limit
HTTP 403.
- What happened: The plan's limit on forms, recipients or webhook endpoints is reached.
- What to do: Upgrade the plan, or delete something you no longer need.
address_unavailable
HTTP 422.
- What happened: A form without an account can't be created for this address: it declined before, it bounced, or it's a disposable address.
- What to do: Sign up at wrenform.com/sign-in instead, or use another address.
quick_forms_unavailable
HTTP 503.
- What happened: Forms without an account are paused for a while to stop abuse.
- What to do: Try again later, or sign up at wrenform.com/sign-in.
timeout
HTTP 504.
- What happened: An AI tool call took longer than 30 seconds.
- What to do: Call the tool again. If it keeps happening, tell us with the time of the call.
Not errors
- Spam gets the same success response as a real submission, so bots learn nothing. Look in the form's Spam tab.
- Over your monthly quota, submissions are still stored and answered with success; they just aren't emailed. Only at three times the quota do requests get
quota_exceeded.
Test it
Post to a form ID that doesn't exist with Accept: application/json. You should get 404 and the form_not_found object.
Next steps
- My form isn't working: start from the symptom when you don't have a code.
- Fields and limits: the limits behind the
4xxcodes. - Spam: the rate limits behind
rate_limited. - Still stuck? Write to hello [at] wrenform.com with the
X-Request-Id.