# Error codes

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

Last updated 2026-11-19. Web version: https://wrenform.com/docs/errors

```json
{
  "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](/docs/api) and the [MCP server](/docs/mcp), 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](/docs/troubleshooting): start from the symptom when you don't have a code.
- [Fields and limits](/docs/fields): the limits behind the `4xx` codes.
- [Spam](/docs/spam): the rate limits behind `rate_limited`.
- Still stuck? Write to hello [at] wrenform.com with the `X-Request-Id`.
