Skip to content
Wrenform

Docs / Reference

Error codes

When the endpoint rejects a submission, nothing is stored. Each error has a stable code, listed here.

Last updated 2026-11-19View as Markdown
{
  "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-Policy is no-referrer or same-origin also 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 4xx codes.
  • Spam: the rate limits behind rate_limited.
  • Still stuck? Write to hello [at] wrenform.com with the X-Request-Id.

Something wrong or unclear on this page? Report a problem: write to hello [at] wrenform.com with the page address (/docs/errors).