Skip to content

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/v1 endpoints answer message and code. A flow that cannot go live also lists every problem in problems. See Going 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

StatusReasonCause and fix
400The submission is empty.The body has no answers and no files. Send at least one answer.
400The body is not valid JSON.Check the JSON, for example with JSON.stringify instead of building it by hand.
400Send the answers as one JSON object...The JSON is a list or a plain value. Send one object.
400The 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.
401That 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.
403Submissions from ... are not allowed for this form...The website is not in the form's allowed websites. Add it under Settings, Allowed websites.
403This form source is paused...Resume the source in the Connect tab or with PATCH /api/v1/sources/{id}.
403This 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.
404This form endpoint does not exist...No source has this key, or it is not 6 to 64 letters and digits. Copy the address again.
405Send submissions with POST.Use POST. GET and OPTIONS are answered too, anything else is not.
413This submission is too large. The limit is 25 MB.Send fewer or smaller files.
413The answers are too long. Keep them under 64 KB in total.Shorten the answers, or send long content as a file.
413Send 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.
422Please 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.
415Send 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.
429Too many submissions from this address. Please wait a minute...More than 120 posts a minute from one address. Slow down, or spread the load.
429Too 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.
429This 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.
500The submission could not be saved. Please try again.Something failed on our side. Try again with the same Idempotency-Key.

API endpoints

StatusCodeCause and fix
400invalid-requestA 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.
400invalid-statusThe status filter of a list is not one of its values.
400url-invalidA destination address was refused, for example because it is not https or points at a private network.
400data-invalidThe data of a test submission is not an object of answers.
400prompt-missingAn AI draft was asked for without a prompt.
400prompt-too-shortThe prompt of an AI draft needs a few more words.
401unauthenticatedNo API key was sent. Add Authorization: Bearer <key>.
401invalid-keyThe key is wrong or was revoked, or its workspace was deleted. Create a new one on the API keys page.
402plan-limitCreating this would go past a limit of your plan. The message says which plan has room.
403read-only-keyThe key is read only and the request would change something. Use a key with full access. See Access levels.
404not-foundNothing with that id in this workspace. Ids of another workspace answer the same way.
405method-not-allowedThe address does not take this method. The Allow header lists the ones it takes.
409spamFlows cannot run again on a submission marked as spam. Release it first.
409key-takenThe endpoint address is in use. Rotate the key to get a new one.
413too-largeThe form or flow is too large to save.
415unsupported-content-typeThe body was not sent as JSON.
422flow-not-readyThe flow cannot go live yet. Every problem is listed in problems.
429rate-limitedMore 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.
429plan-limitThe AI drafts of your plan are used up for today. They come back tomorrow.
402, 403, 429, 503ai-unavailableAI is not available or busy just now. Try again in a moment.
502ai-emptyAI could not turn the prompt into fields. Describe the questions you want to ask.
500server-errorSomething 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

StatusRetry?How
429YesWait 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, 503YesAfter a few seconds, and on the submission endpoint with the same Idempotency-Key, so nothing is stored twice.
Network error or timeoutYesThe same as a 500.
400, 401, 402, 403, 404, 405, 409, 413, 415, 422NoThe 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

LimitValue
API requests per key120 a minute, reads and changes together
AI form draftsYour plan's daily drafts, shared with the dashboard, and 20 an hour per key
Submissions per address, every endpoint120 a minute
Submissions per visitor, per formSet on each form, 30 an hour by default, 0 turns it off
Request size25 MB
Answers without files64 KB in total
Fields per submission200
Characters per value10,000
Values per list100
Files10 per submission, 10 MB each
Idempotency-Key200 characters, remembered for 24 hours per source
Duplicate window10 seconds for identical answers from the same source
New fields learned50 per submission
Submissions page size1 to 100, 50 by default
Forms and flowsUp to 200 fields per form, 200 steps and 400 connections per flow
Monthly submissions on Starter250 submissions a month
Monthly submissions on Pro10,000 submissions a month
Monthly submissions on EnterpriseUnlimited submissions
Forms, flows, sources, destinations, members and API keysDepends 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.