> ## 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.

# Error reference

> Every error /submit can return - code, HTTP status, and meaning.

Every error `/submit` returns follows the same shape: the matching HTTP status code,
plus a JSON body with `success: false`, a stable `code`, and a human-readable `message`.

```json theme={null}
{ "success": false, "code": "invalid_access_key", "message": "The access_key is not valid." }
```

`code` is the part worth branching on - it doesn't change between releases the way
`message` copy might. If you're building an agent or any code that needs to react to a
specific failure (retry, prompt for a fix, surface a specific UI state), read `code`,
not `message`.

## All codes

| Code                   | HTTP | Meaning                                                    |
| ---------------------- | ---- | ---------------------------------------------------------- |
| `missing_access_key`   | 400  | No access\_key was provided.                               |
| `invalid_access_key`   | 401  | The access\_key is not valid.                              |
| `invalid_body`         | 400  | The request body could not be parsed as JSON or form data. |
| `empty_submission`     | 400  | The submission contained no fields.                        |
| `payload_too_large`    | 413  | The request body is too large.                             |
| `method_not_allowed`   | 405  | Only POST is allowed on this endpoint.                     |
| `domain_not_allowed`   | 403  | This form does not accept submissions from this domain.    |
| `internal_error`       | 500  | An unexpected error occurred.                              |
| `rate_limited`         | 429  | Too many requests. Please slow down and try again shortly. |
| `invalid_redirect`     | 400  | The redirect URL is not allowed for this form.             |
| `too_many_fields`      | 400  | The submission has too many fields.                        |
| `field_too_large`      | 400  | A submission field is too large.                           |
| `too_many_files`       | 400  | Too many files in this submission.                         |
| `file_too_large`       | 413  | An uploaded file is too large.                             |
| `empty_file`           | 400  | An uploaded file was empty.                                |
| `storage_cap_exceeded` | 413  | This account's file storage limit has been reached.        |
| `upgrade_required`     | 403  | This feature requires a Pro plan.                          |

## Using this table

* **Humans**: match the `code` your form's error handler logged (or the one shown in a
  failed dashboard test send) against this table to find out what went wrong.
* **Agents**: read `code` to self-correct. `invalid_access_key` means re-check the key
  you wired in; `domain_not_allowed` means the submitting origin isn't on the form's
  allowlist yet; `upgrade_required` means the field or feature you're trying to use is
  Pro-only. See [Troubleshooting & FAQ](/docs/reference/troubleshooting-faq) for the common
  ones mapped to fixes.

<CardGroup cols={2}>
  <Card title="Options reference" icon="sliders" href="/docs/reference/options">
    The reserved fields and per-form config each error relates to.
  </Card>

  <Card title="Troubleshooting & FAQ" icon="circle-question" href="/docs/reference/troubleshooting-faq">
    Common issues, mapped to the codes above.
  </Card>
</CardGroup>