Errors

Every error the Platform API returns is a Platform Error: a JSON body with at least three fields.

• code is a stable identifier from the catalog below. It is the field to branch on.
• message is a human-readable explanation. It may change between Contract Revisions and is not part of the contract.
• request_id identifies the request. It is also sent as the X-Request-Id response header; quote it when you contact support.

Some codes add fields of their own, listed under Variant fields. A client that meets a code it does not know should fall back on the HTTP status.

Status and code catalog

Status	Code
400	INVALID_INPUT
401	UNAUTHORIZED
401	PERSONAL_ACCESS_TOKEN_EXPIRED
401	PERSONAL_ACCESS_TOKEN_REVOKED
402	PLAN_LIMIT_REACHED
402	PRO_FEATURE_REQUIRED
403	FORBIDDEN
403	FORM_PUBLISH_EMAIL_UNVERIFIED
403	ORGANIZATION_MEMBER_BLOCKED
403	PERSONAL_ACCESS_TOKEN_NOT_PERMITTED
404	NOT_FOUND
404	FORM_NOT_PUBLISHED
409	NO_DRAFT_DURING_PUBLISH
409	FORM_ARCHIVED
409	FORM_CONVERSION_BLOCKED
409	FORM_PUBLISH_REVISION_CONFLICT
413	PAYLOAD_TOO_LARGE
422	FORM_PUBLISH_VALIDATION_FAILED
422	FORM_SAFETY_REJECTED
429	TOO_MANY_REQUESTS
429	API_COOLDOWN
500	SERVER
503	AI_SERVICE_UNAVAILABLE
503	SERVICE_UNAVAILABLE

What each group means:

• 400 INVALID_INPUT: the request body or parameters failed Draft Write Validation or a basic shape check.
• 401 UNAUTHORIZED, PERSONAL_ACCESS_TOKEN_EXPIRED, PERSONAL_ACCESS_TOKEN_REVOKED: the token is missing, malformed, unknown, expired, or revoked. See Authentication.
• 402 PLAN_LIMIT_REACHED, PRO_FEATURE_REQUIRED: the organization’s plan blocks the action, not the token.
• 403 FORBIDDEN, ORGANIZATION_MEMBER_BLOCKED, PERSONAL_ACCESS_TOKEN_NOT_PERMITTED, FORM_PUBLISH_EMAIL_UNVERIFIED: the token, or the member it belongs to, lacks permission for the action. FORM_PUBLISH_EMAIL_UNVERIFIED means the token owner has not verified their email address; verify it in the app, then publish again.
• 404 NOT_FOUND, FORM_NOT_PUBLISHED: the resource does not exist for this organization or is in Trash, or the form has no published version yet.
• 409 NO_DRAFT_DURING_PUBLISH, FORM_ARCHIVED, FORM_CONVERSION_BLOCKED, FORM_PUBLISH_REVISION_CONFLICT: the request conflicts with the form’s current state. NO_DRAFT_DURING_PUBLISH means the form holds no draft to validate or publish. FORM_PUBLISH_REVISION_CONFLICT means the form changed while it was being published; publish again. FORM_ARCHIVED means the form is archived, so it has no editable draft and nothing to publish; restore it in the app before trying again.
• 413 PAYLOAD_TOO_LARGE: the body exceeds 4 MiB.
• 422 FORM_PUBLISH_VALIDATION_FAILED, FORM_SAFETY_REJECTED: the request was understood but cannot be completed, because the draft has Publish Issues or automated safety checks flagged the form. FORM_SAFETY_REJECTED usually answers a publish, and can also answer a draft write that sets meta_title, meta_description, or respondent email content to abusive text; the form and its owner are held for review, so do not retry.
• 429 TOO_MANY_REQUESTS, API_COOLDOWN: the call does not fit the organization’s API budget, or the organization is in an API Cooldown. See Rate limits and plans.
• 500 SERVER: an unexpected server error.
• 503 AI_SERVICE_UNAVAILABLE, SERVICE_UNAVAILABLE: a dependency, or the service itself, is temporarily unavailable. SERVICE_UNAVAILABLE covers a saturated write pool, the organization’s two running submission exports, and a publish whose automated safety check could not run.

Variant fields

Code	Extra fields
INVALID_INPUT	issues, an array in which each entry has a code, a message, a path (a JSON path array into the request body), params when the message is built from values such as a limit, and, for node types and enum values, accepted_values. An unknown key is reported at its own path. Branch on code; to show the issue in your own words or language, write text per code and fill it from params.
FORM_PUBLISH_VALIDATION_FAILED	issues, an array of Publish Issues, each with code, message, a path array, page_public_id, and node_public_id. The last two are nullable.
Every 403 code	required_permission, the permission the member lacks, or null when no single permission applies. FORBIDDEN names forms:read, forms:write, templates:read, templates:write, or form_publish; PERSONAL_ACCESS_TOKEN_NOT_PERMITTED names personal_access_tokens.
PLAN_LIMIT_REACHED	plan, limit (an object with key, max, and current), and upgrade_url.
PRO_FEATURE_REQUIRED	plan, feature, path, and upgrade_url. path is a slash-separated string naming the field that needs Pro, such as properties/meta_title or workspace_public_id, or an empty string when no single field is to blame.
TOO_MANY_REQUESTS, API_COOLDOWN	policy, plan, limit, used, remaining, cost, window_seconds, cooldown_until, resets_at, retry_after_seconds, and upgrade_url, described in Rate limits and plans. A TOO_MANY_REQUESTS from the per-IP limit carries only the envelope and a Retry-After header.
FORM_CONVERSION_BLOCKED	reason: published or has_submissions. See Private Templates.
SERVICE_UNAVAILABLE, AI_SERVICE_UNAVAILABLE	retry_after_seconds, the same delay the Retry-After header carries. AI_SERVICE_UNAVAILABLE always has it, and so does every SERVICE_UNAVAILABLE the Platform API sends for the causes listed above.

Every other code carries the three envelope fields and nothing more.

Publish Issues

Publish Issues are the problems that block a publish. The validate call returns them without changing anything, and a failed publish returns them in a 422 FORM_PUBLISH_VALIDATION_FAILED. Each issue has a code and a default message, plus these fields that locate the problem:

• path is an array of property names and numeric indexes into the Draft Document, such as ["pages", 1, "nodes", 0, "meta", "select_options_data"]. It is an empty array when the issue is about the form as a whole rather than one value. It has the same shape as the path of an INVALID_INPUT issue.
• page_public_id is the page to fix, or null when the issue is not about one page.
• node_public_id is the block to fix, or null when the issue is not about one block.

Hidden pages and nodes never produce issues, with two exceptions: FORM_PUBLISH_FINAL_PAGE_HIDDEN and FORM_PUBLISH_ALL_PAGES_HIDDEN describe the hidden state itself.

Every code is listed in the code enum of the response of Validate a draft without publishing.

By concern:

• Structure and endings. FORM_PUBLISH_DRAFT_INVALID means the stored draft cannot be read as a form, FORM_PUBLISH_BLUEPRINT_INVALID that it fails the blueprint shape in a way no specific code covers, and FORM_PUBLISH_BLUEPRINT_TOO_LARGE that the whole form is too large to publish. FORM_PUBLISH_MISSING_FINAL_PAGE, FORM_PUBLISH_MULTIPLE_FINAL_PAGES, and FORM_PUBLISH_FINAL_PAGE_POSITION cover no ending, more than ten, or an ending followed by another kind of page; FORM_PUBLISH_FINAL_PAGE_NODES an ending that is empty, holds a question, or holds more than one Thank You node; FORM_PUBLISH_THANK_YOU_PLACEMENT a Thank You node on another page; FORM_PUBLISH_FINAL_PAGE_HIDDEN and FORM_PUBLISH_ALL_PAGES_HIDDEN a hidden ending or a form with no other visible page.
• Limits. FORM_PUBLISH_TOO_MANY_PAGES, FORM_PUBLISH_TOO_MANY_NODES, FORM_PUBLISH_TOO_MANY_PAGE_NODES, FORM_PUBLISH_TOO_MANY_OPTIONS, FORM_PUBLISH_TOO_MANY_TOTAL_OPTIONS, FORM_PUBLISH_TOO_MANY_MATRIX_ROWS, and FORM_PUBLISH_TOO_MANY_MATRIX_COLUMNS report an exceeded limit.
• Questions and options. FORM_PUBLISH_MISSING_QUESTION means no normal page holds a question; FORM_PUBLISH_MISSING_OPTIONS a choice question without options; FORM_PUBLISH_MISSING_MATRIX_ROWS a matrix without rows. FORM_PUBLISH_NUMBER_SETTINGS_INVALID means a number question whose min, max, step, and default value do not fit together.
• Entrypoint and auto-jump. FORM_PUBLISH_MULTIPLE_ENTRYPOINTS, FORM_PUBLISH_ENTRYPOINT_FINAL_PAGE, and FORM_PUBLISH_ENTRYPOINT_POSITION cover an entrypoint that is duplicated, on an ending, or not the first non-final page; FORM_PUBLISH_AUTO_JUMP_INVALID a page that enables auto-jump without exactly one eligible question.
• Answer piping. FORM_PUBLISH_DANGLING_PIPE means form content references an answer or hidden value that no longer exists; see Answer piping.
• Logic. Publishing does not check logic rules. A rule that no longer fits the form, for example one that points at a deleted question, is skipped when respondents fill in the form, so no Publish Issue is about logic.
• Account, plan, and safety. These use Platform Error codes and have an empty path, except PRO_FEATURE_REQUIRED, whose path usually names the Pro field. FORM_PUBLISH_EMAIL_UNVERIFIED means the token owner must verify their email address first, PRO_FEATURE_REQUIRED that the draft uses a feature the plan does not include, and FORM_SAFETY_REJECTED that automated safety checks flagged the form.

The page-level codes are explained one by one in Pages.

Retry rules

• TOO_MANY_REQUESTS: wait for Retry-After, then retry. With policy: "burst", the call waits for resets_at unless you send cheaper calls instead.
• API_COOLDOWN: stop until cooldown_until; every call before then is rejected.
• SERVICE_UNAVAILABLE and AI_SERVICE_UNAVAILABLE are transient. Retry after Retry-After, or after a few seconds when it is absent.
• A repeated identical draft write is a safe no-op, so a write whose response you lost can be sent again. The same holds for unpublish, close, reopen, restore, move, and an access patch that changes nothing: each answers 200 and writes nothing. publish is safe to repeat too: a draft that has not changed since the last publish keeps its version number, so a retry after a lost response does not create a new version.
• FORM_PUBLISH_REVISION_CONFLICT is safe to retry: nothing was published.
• Never retry any other 4xx error unchanged: the same request gets the same answer.
• On SERVER, report the request_id to support rather than retrying blindly.