Limites e erros de validação do trulyform

O que você precisa saber

O trulyform verifica o formulário em dois momentos. Ao salvar, recusa uma definição com formato errado e não salva nada. Ao publicar, também exige que o rascunho não tenha nenhum item em issues.
Dá para salvar um rascunho com problemas, como uma pergunta sem título, e montar o formulário aos poucos.
Todo erro indica onde está o problema: um caminho na definição, nos erros ao salvar, ou um nodeId, nos problemas de publicação.
Os limites abaixo não podem ser ultrapassados.

Limites

A referência técnica a seguir é gerada a partir do código e está em inglês, como os assistentes de IA a leem. As mensagens de erro aparecem como a API as retorna, em inglês.

Limite	Valor	Observações
`definition_bytes`	2.000.000	Maximum size of the whole definition as UTF-8 JSON.
`fields`	200	Questions per form.
`options_per_field`	250	Choices per question (matrix columns included).
`rows_per_field`	100	Rows per matrix question.
`rules`	300	Logic rules per form.
`conditions_per_rule`	20	Conditions per logic rule.
`calculations`	100	Calculations per form.
`expression_depth`	12	Nesting depth of one calculation expression.
`calculation_name_length`	100	Characters per calculation name.
`hidden_fields`	30	Hidden URL parameters captured per form.
`text_length`	10.000	Characters per rich-text text node.
`label_length`	2.000	Characters per choice or row label.
`button_length`	100	Characters per button label.
`max_files_per_answer`	10	Largest maxFiles setting. The respondent can upload no more than the form owner's plan allows: Free 1 file, Pro 10 files, Business 10 files.
`max_file_megabytes`	10	Largest file a respondent can upload, in MB, whatever maxSizeMB says.

Limites por plano

Lógica, cálculos e todos os tipos de pergunta estão disponíveis em todos os planos. Os itens abaixo dependem do plano do dono do formulário:

Plano	Arquivos por resposta	Armazenamento de arquivos	Respostas parciais	Logo próprio
Free	1	10 MB	Não	Não
Pro	10	1 GB	Sim	Não
Business	10	10 GB	Sim	Sim

Cada pessoa pode fazer até 120 requisições MCP por minuto.

Erros ao salvar

Quando o formato está errado, save_form_draft retorna validation_failed com um objeto errors, que liga cada caminho às mensagens de erro dele:

Um erro ao salvar

{
    "code": "validation_failed",
    "message": "Correct the indicated fields and try again.",
    "errors": { "fields.0.kind": ["The selected fields.0.kind is invalid."] }
}

Selecione o texto para copiá-lo.

Os caminhos partem da definição: fields.0.kind é o kind da primeira pergunta. Nos erros de texto formatado, os caminhos começam com definition., como definition.fields.0.title, e apontam para o mesmo lugar. A lista docs do erro indica as seções que o explicam; passe uma delas para read_docs.

Mensagem	Causa	Correção
The selected fields.0.kind is invalid.	Não é um dos tipos de pergunta	Use um dos tipos de Tipos de pergunta.
The fields.0.id field must be a valid UUID.	O ID não é um UUIDv7	Use um UUIDv7. Veja Identificadores.
The fields.0.id field must be lowercase.	ID com letras maiúsculas	Escreva os IDs em minúsculas.
The fields.0.id field has a duplicate value.	Duas perguntas com o mesmo ID	Dê um ID diferente a cada uma.
Every question, choice, row, rule, and calculation needs a unique identifier.	Um ID usado duas vezes, por exemplo numa opção e numa pergunta	Use um ID novo para cada item.
Use supported text formatting.	Um título ou uma descrição está como string, ou usa um nó ou uma formatação desconhecidos	Escreva como texto formatado.
Use paragraphs with inline text and answer references.	Nós de texto formatado no lugar errado, como texto solto direto no doc	Coloque o texto dentro de um parágrafo, e o parágrafo dentro do doc.
The fields.0.settings field must be an array.	`settings` tem uma chave que não é configuração, como `options` ou `required`	Remova a chave. As chaves permitidas estão em Configurações.
The definition field must be an array.	Uma chave principal desconhecida, como `pages`	Envie só as chaves principais.
The fields.0.required field must be true or false.	Uma string, como "true"	Envie um booleano JSON.
The theme.primary field format is invalid.	Uma cor fora do formato #RRGGBB	Use uma cor hexadecimal de seis dígitos, como #2563eb.
Use a lowercase UUIDv7 asset identifier or null.	Uma string vazia como ID de arquivo	Use null.
This form exceeds the 2 MB definition limit. Remove unused content and try again.	A definição passa de 2 MB	Encurte os textos ou remova perguntas.

Problemas de publicação

Os issues aparecem em get_form, em todo retorno de save_form_draft e, quando a publicação falha, no erro de publish_form:

Um erro ao publicar

{
    "code": "validation_failed",
    "message": "Resolve these issues before publishing.",
    "issues": [
        { "nodeId": "01990000-0000-7000-8000-000000000001", "path": "options", "message": "Add at least two choices.", "severity": "error" }
    ]
}

Selecione o texto para copiá-lo.

nodeId é o ID de uma pergunta, regra ou cálculo, ou então form, theme, welcome ou ending. path indica qual parte corrigir.

Problema	Correção
Add at least one question.	Adicione uma pergunta em `fields`.
Write your question.	Dê um título à pergunta. Um texto informativo pode ficar só com a descrição.
The title is empty and your text is in the description. Move it to the title.	Passe o texto da pergunta de `description` para `title`.
Add at least two choices.	Adicione opções à pergunta de escolha.
Give every choice a label.	Preencha o `label` de todas as opções.
Add a label for every matrix row.	Adicione linhas à matriz e dê um rótulo a cada uma.
Statements cannot require or collect answers.	Defina `required` como false e deixe `options` e `rows` vazios.
Use a response limit above zero, or no limit.	Defina `fillLimit` como null ou um número maior que 0.
Use a numeric choice score.	Escreva o `score` como string decimal, como "10" ou "2.5".
Use whole-number scale limits with at most 11 choices.	Use números inteiros no `min` e no `max` da escala de opinião, com diferença de no máximo 10.
Minimum must not exceed maximum.	Inverta `min` e `max`.
Increase the contrast of form text in Design so everyone can read it.	Use um `foreground` mais escuro ou um `background` mais claro. Veja Cores legíveis.
Increase the contrast of button text in Design so everyone can read it.	Ajuste `buttonText` ou `primary` até o contraste entre eles chegar a 4,5:1.
Choose a question and a target later in the form.	O `sourceId` da regra precisa vir antes do `targetId`. Veja Regras de lógica.
Conditions must use an answer available before this rule runs.	Baseie as condições na pergunta de origem da regra ou em perguntas anteriores.
Choose an operator supported by this answer type.	Use um operador aceito pelo tipo de pergunta. Veja Condições.
Set a comparison value.	Adicione um `value` à condição.
This condition references a choice that was removed. Choose an available answer.	Use um ID de opção que ainda exista.
Name this calculation.	Dê um `name` ao cálculo.
This calculation has a missing reference or a circular dependency.	Aponte cada referência para um cálculo que existe, sem ciclos. Veja Cálculos.
Piped answers must come from an earlier question.	Coloque o token de resposta depois da pergunta que ele mostra, ou use outra pergunta. Veja Referências de resposta.

Os problemas de intervalo citam o nome da configuração, por exemplo "Set maxFiles between 1 and 10." Use um valor dentro do intervalo indicado em Configurações.

Códigos de erro

Todo erro de ferramenta traz um code e uma message:

Código	Significado	O que fazer
`unauthenticated`	A conexão não está autenticada.	Entre de novo pelo cliente.
`organization_required`	A conta não tem organização.	O usuário precisa entrar em uma organização ou criar uma no trulyform.
`validation_failed`	A entrada é inválida. `errors` ou `issues` explicam o motivo.	Corrija o que eles apontam e tente de novo.
`draft_conflict`	O rascunho mudou depois da revisão enviada, ou um `mutation_id` foi reaproveitado com outro conteúdo. `revision` traz a revisão atual.	Leia o formulário de novo e refaça a alteração.
`not_found`	Esse formulário ou essa resposta não existe nesta organização.	Confira o ID com `list_forms` ou `list_responses`.
`forbidden`	O usuário não tem permissão para isso.	Pergunte ao usuário.
`operation_failed`	Algo inesperado deu errado.	Leia o formulário de novo antes de repetir uma alteração.