# Errors and limits

Every error comes with a status code and a message written for people. The /api/v1 endpoints add a code you can branch on, and the submission endpoint adds the exact reason. This page lists every one of them, what causes it and how to fix it.

**On this page you will learn**

- What an error looks like
- Every error of the submission endpoint
- Every error code of the /api/v1 endpoints
- Which errors are safe to retry, with retry code
- Every limit in one table

## Error shape

*JSON*

```json
{
  "message": "That API key is not valid. It may have been revoked.",
  "code": "invalid-key"
}
```

*JSON*

```json
{
  "message": "This flow is not ready to go live. Fix the problems listed in problems, or save it as a draft.",
  "code": "flow-not-ready",
  "problems": ["..."]
}
```

*JSON*

```json
{
  "ok": false,
  "message": "This form is paused, so it is not taking submissions right now.",
  "reason": "This form is paused, so it is not taking submissions right now."
}
```

- The `/api/v1` endpoints answer `message` and `code`. A flow that cannot go live also lists every problem in `problems`. See [Going live](https://formpik.com/docs/api/flows#go-live).
- The submission endpoint answers `ok`, `message` and `reason`. `message` is the form's own error message when it has one, and `reason` always says what went wrong. Classic form posts that ask for HTML get a short Not sent page instead.
- Branch on the status and the `code`. Show `message` to people as it is, but do not match on its text, which can change.

## Submission endpoint

| Status | Reason | Cause and fix |
| --- | --- | --- |
| 400 | The submission is empty. | The body has no answers and no files. Send at least one answer. |
| 400 | The body is not valid JSON. | Check the JSON, for example with JSON.stringify instead of building it by hand. |
| 400 | Send the answers as one JSON object... | The JSON is a list or a plain value. Send one object. |
| 400 | The form upload could not be read. | The multipart body is broken. Let your HTTP library build it, and do not set the Content-Type yourself with FormData. |
| 401 | That API key is not valid for this workspace. | The Authorization header holds a wrong or revoked key, or one of another workspace. Fix it, or leave the header out. |
| 403 | Submissions from ... are not allowed for this form... | The website is not in the form's allowed websites. Add it under Settings, Allowed websites. |
| 403 | This form source is paused... | Resume the source in the Connect tab or with PATCH /api/v1/sources/{id}. |
| 403 | This form is paused... | Turn Accept submissions back on in the form's settings, or set its status to active. |
| 403 | (no body) | A browser preflight from a website that is not allowed. |
| 404 | This form endpoint does not exist... | No source has this key, or it is not 6 to 64 letters and digits. Copy the address again. |
| 405 | Send submissions with POST. | Use POST. GET and OPTIONS are answered too, anything else is not. |
| 413 | This submission is too large. The limit is 25 MB. | Send fewer or smaller files. |
| 413 | The answers are too long. Keep them under 64 KB in total. | Shorten the answers, or send long content as a file. |
| 413 | Send at most 10 files with one submission. | Split the files over several submissions or zip them. |
| 413 | ... is larger than 10 MB. | Make that file smaller. |
| 422 | Please check the highlighted answers and try again. | Answers break the field rules and the form refuses them. `errors` says what to fix for each field. Fix the answers, or turn off Refuse answers that break the field rules. |
| 415 | Send the form as JSON, a regular form post or a multipart upload. | Set Content-Type to application/json, application/x-www-form-urlencoded or multipart/form-data. |
| 429 | Too many submissions from this address. Please wait a minute... | More than 120 posts a minute from one address. Slow down, or spread the load. |
| 429 | Too many submissions from this address in the last hour... | The form's limit per visitor was reached. Raise it in the form's settings, or set it to 0 to turn it off. |
| 429 | This workspace reached its monthly submission limit... | The plan's monthly submissions are used up. They reset at the start of the next month in UTC, or change plan. |
| 500 | The submission could not be saved. Please try again. | Something failed on our side. Try again with the same Idempotency-Key. |

## API endpoints

| Status | Code | Cause and fix |
| --- | --- | --- |
| 400 | `invalid-request` | A property is missing, has the wrong type or a value that is not allowed, or the body is a list. The message names it, such as fields[2].type. |
| 400 | `invalid-status` | The status filter of a list is not one of its values. |
| 400 | `url-invalid` | A destination address was refused, for example because it is not https or points at a private network. |
| 400 | `data-invalid` | The data of a test submission is not an object of answers. |
| 400 | `prompt-missing` | An AI draft was asked for without a prompt. |
| 400 | `prompt-too-short` | The prompt of an AI draft needs a few more words. |
| 400 | `slug-invalid` | A share link slug is too short, too long, or uses characters other than lowercase letters, numbers and dashes. |
| 400 | `role-invalid` | The role is not admin, editor or viewer. |
| 400 | `email-invalid` | The email address of an invitation is not valid. |
| 400 | `email-plus` | An invitation to an address with a + in it, which cannot join. Invite the address without the + part. |
| 400 | `email-disposable` | An invitation to a temporary mailbox, which cannot join. |
| 401 | `unauthenticated` | No API key was sent. Add `Authorization: Bearer <key>`. |
| 401 | `invalid-key` | The key is wrong or was revoked, or its workspace was deleted. Create a new one on the API keys page. |
| 402 | `plan-limit` | Creating this would go past a limit of your plan. The message says which plan has room. |
| 403 | `read-only-key` | The key is read only and the request would change something. Use a key with full access. See [Access levels](https://formpik.com/docs/api#access). |
| 403 | `permission-escalation` | The role change needs a permission the key or the person does not have, or acts on someone with more access. See [What nobody can do](https://formpik.com/docs/api/roles#rules). |
| 403 | `default-role` | The default roles (owner, admin, editor, viewer) cannot be changed or deleted. Create a role of your own instead. |
| 400 | `role-invalid` | The role id is not a role of this workspace, or it is owner, which is never given. |
| 400 | `permission-invalid` | A permission key is not one of those List permissions answers. |
| 409 | `role-name-taken` | Another role of the workspace, or a default role, already has that name. |
| 409 | `role-limit` | The workspace has as many roles of its own as it can have. Delete one first. |
| 403 | `admin-key-required` | The team, API keys, connected apps, workspace settings and billing need a key with admin access. |
| 403 | `forbidden` | The owner cannot be removed or given another role, and an API key cannot hand the workspace over. |
| 404 | `not-found` | Nothing with that id in this workspace. Ids of another workspace answer the same way. |
| 405 | `method-not-allowed` | The address does not take this method. The Allow header lists the ones it takes. |
| 409 | `spam` | Flows cannot run again on a submission marked as spam. Release it first. |
| 409 | `key-taken` | The endpoint address is in use. Rotate the key to get a new one. |
| 409 | `slug-taken` | Another form already has that share link. Pick another slug. |
| 409 | `already-member` | The person you invited is already on the team. |
| 409 | `no-subscription` | The workspace has no paid plan to cancel or keep. |
| 413 | `too-large` | The form or flow is too large to save. |
| 415 | `unsupported-content-type` | The body was not sent as JSON. |
| 422 | `flow-not-ready` | The flow cannot go live yet. Every problem is listed in problems. |
| 429 | `rate-limited` | More than 120 requests in a minute with this key, or more than 20 AI drafts in an hour. Wait for the seconds in Retry-After. |
| 429 | `plan-limit` | The AI drafts of your plan are used up for today. They come back at midnight UTC. |
| 402, 403, 429, 503 | `ai-unavailable` | AI is not available or busy just now. Try again in a moment. |
| 502 | `ai-empty` | AI could not turn the prompt into fields. Describe the questions you want to ask. |
| 500 | `server-error` | Something failed on our side. Try again shortly. |

The method is checked first, then the key, then the rate limit, then the access, so a `DELETE` on an address that only reads, such as `/api/v1/workspace`, gets a `405` even without a key, and a read only key over the rate limit gets a `429` before its `403`.

## What to retry

| Status | Retry? | How |
| --- | --- | --- |
| 429 | Yes | Wait first: the Retry-After seconds on /api/v1, a minute on the submission endpoint. Monthly submissions and daily AI drafts only free up later. |
| 500, 502, 503 | Yes | After a few seconds, and on the submission endpoint with the same Idempotency-Key, so nothing is stored twice. |
| Network error or timeout | Yes | The same as a 500. |
| 400, 401, 402, 403, 404, 405, 409, 413, 415, 422 | No | The same request fails again. Fix the cause first. |

*JavaScript*

```js
async function call(url, options, attempts = 3) {
  for (let attempt = 1; ; attempt++) {
    const response = await fetch(url, options)

    if (response.ok) return response.json()

    const error = await response.json().catch(() => ({}))
    const retryable = response.status === 429 || response.status >= 500

    if (!retryable || attempt === attempts) {
      throw new Error(`${response.status} ${error.code ?? ""}: ${error.message}`)
    }

    const seconds = Number(response.headers.get("Retry-After")) || 2 ** attempt
    await new Promise(resolve => setTimeout(resolve, seconds * 1000))
  }
}
```

*Python*

```python
import time

import requests

def call(method, url, attempts=3, **kwargs):
    for attempt in range(1, attempts + 1):
        response = requests.request(method, url, timeout=30, **kwargs)

        if response.ok:
            return response.json()

        retryable = response.status_code == 429 or response.status_code >= 500

        if not retryable or attempt == attempts:
            error = response.json()
            raise RuntimeError(f"{response.status_code} {error.get('code', '')}: {error['message']}")

        time.sleep(int(response.headers.get("Retry-After", 2 ** attempt)))
```

> **Failed deliveries are not API errors**
>
> The endpoint answers before the flows run. When a step fails later, such as a webhook that answers with an error, the submission is marked Needs attention and shows the reason in the inbox. See [When a delivery fails](https://formpik.com/docs/destinations#failures).

## All limits in one place

| Limit | Value |
| --- | --- |
| API requests per key | 120 a minute, reads and changes together |
| AI form drafts | Your plan's daily drafts, shared with the dashboard, and 20 an hour per key |
| Submissions per address, every endpoint | 120 a minute |
| Submissions per visitor, per form | Set on each form, 30 an hour by default, 0 turns it off |
| Request size | 25 MB |
| Answers without files | 64 KB in total |
| Fields per submission | 200 |
| Characters per value | 10,000 |
| Values per list | 100 |
| Files | 10 per submission, 10 MB each |
| Idempotency-Key | 200 characters, remembered for 24 hours per source |
| Duplicate window | 10 seconds for identical answers from the same source |
| New fields learned | 50 per submission |
| Submissions page size | 1 to 100, 50 by default |
| Forms and flows | Up to 200 fields per form, 200 steps and 400 connections per flow |
| Monthly submissions on Starter | 250 submissions a month |
| Monthly submissions on Pro | 10,000 submissions a month |
| Monthly submissions on Max | Unlimited submissions |
| Forms, flows, sources, destinations, members and API keys | [Depends on your plan](https://formpik.com/docs/plans) |

Monthly submissions count every submission stored through an endpoint since the start of the month in UTC, spam included and test submissions left out.

## Common questions

### I get a 403 from my own website. Why?

The form limits its allowed websites and your page's domain is not in the list. Add the main domain: it covers every subdomain, such as www.

### Why does my POST to /api/v1/forms get a 403?

The key is read only, and the answer has the code `read-only-key`. Create a key with full access for code that makes changes.

### What happens to submissions above the monthly limit?

They are refused with a 429 and not stored, and your website shows the error. Nothing already stored is deleted.

### Why does a create answer 402?

Your plan has no room for another form, flow, source or destination. [GET /api/v1/workspace](https://formpik.com/docs/api/workspace) shows the limits and what is in use.

- [API overview](https://formpik.com/docs/api): Base address, keys and every endpoint.
- [Send a submission](https://formpik.com/docs/api/submit): The endpoint and its answers.
- [Plans and limits](https://formpik.com/docs/plans): What each plan includes.

---

Source: https://formpik.com/docs/api/errors
