API reference
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
{
"message": "That API key is not valid. It may have been revoked.",
"code": "invalid-key"
}- The
/api/v1endpoints answermessageandcode. A flow that cannot go live also lists every problem inproblems. See Going live. - The submission endpoint answers
ok,messageandreason.messageis the form's own error message when it has one, andreasonalways 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. Showmessageto 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. |
| 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. |
| 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. |
| 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 tomorrow. |
| 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
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))
}
}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 Enterprise | Unlimited submissions |
| Forms, flows, sources, destinations, members and API keys | Depends on your plan |
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 shows the limits and what is in use.