Erros

Todos os códigos de erro que o Ikiform retorna, com status HTTP, causa e correção.

Os envios de formulário e a API REST compartilham o mesmo envelope de erro. Requisições JSON o recebem com o status HTTP correspondente; envios de formulário pelo navegador recebem uma página de erro hospedada com a mesma mensagem e o mesmo status.

O envelope de erro

Erro

{
  "ok": false,
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Please slow down."
  },
  "request_id": "req_01k7v2c9t3e8m5q4x6z0a1b2c3"
}

error.code é estável; use-o nas suas condições. error.message é um texto em inglês simples para pessoas e pode mudar.
error.fields aparece em erros de validação, indexado pelo id do campo, cada um com uma lista de mensagens. Erros sobre o corpo inteiro usam a chave _form.
error.challenge_url aparece em challenge_required.
request_id corresponde ao header X-Request-Id que toda resposta traz.
Respostas com limite de taxa atingido trazem Retry-After em segundos. Os dois headers podem ser lidos pelo código no navegador.

Códigos

Status	Código	Onde
400	`invalid_body`	Envio
400	`invalid_request`	API
401	`unauthorized`	API
402	`plan_required`	Envio
403	`forbidden`	Ambos
403	`origin_not_allowed`	Envio
403	`form_paused`	Envio
403	`captcha_failed`	Envio
403	`challenge_required`	Envio
404	`not_found`	Ambos
405	`method_not_allowed`	API
409	`idempotency_in_progress`	Envio
413	`payload_too_large`	Envio
415	`unsupported_media_type`	Envio
415	`unsupported_charset`	Envio
422	`validation_failed`	Envio
422	`files_not_supported`	Envio
422	`too_deep`	Envio
422	`idempotency_mismatch`	Envio
429	`rate_limited`	Ambos
429	`quota_exceeded`	Envio
500	`server_error`	Ambos

400 invalid_body

Mensagem	`The request body could not be read.`
Causa	JSON ou multipart malformado, um array ou string JSON em vez de um objeto, ou uma chave de idempotência com mais de 255 caracteres.
Correção	Envie um único objeto JSON, ou deixe o navegador ou o `FormData` montar o corpo.

400 invalid_request

Mensagem	`The request is invalid.`
Causa	`limit`, `status`, `form_id` ou `cursor` é inválido. A mensagem indica o parâmetro.
Correção	Use `limit` de 1 a 100, `status` `received` ou `spam`, um id `frm_` real e cursores exatamente como foram retornados.

401 unauthorized

Mensagem	`A valid API key is required.`
Causa	Sem header `Authorization`, não é um token Bearer, ou a chave é desconhecida, revogada ou expirada.
Correção	Envie `Authorization: Bearer ik_sk_...` com uma chave secreta válida.

402 plan_required

Mensagem	`This form isn't accepting submissions right now.`
Causa	O workspace não tem plano ativo. Isso só pode acontecer depois que a cobrança for ativada.
Correção	Escolha um plano no painel em Settings.

403 forbidden

Mensagem	`You do not have access to this resource.`
Causa	A chave de API está malformada, pertence a outro workspace, é publicável na API REST ou não tem o escopo necessário.
Correção	Use uma chave secreta deste workspace com o escopo indicado na mensagem.

403 origin_not_allowed

Mensagem	`This form does not accept submissions from this site.`
Causa	O envio veio de um site fora dos domínios permitidos do formulário e o formulário rejeita divergências, ou uma chave publicável foi usada a partir de um domínio que não está listado na chave.
Correção	Adicione o site em Allowed domains ou aos domínios da chave. Para envios de servidor, use uma chave secreta.

403 form_paused

Mensagem	`This form is not accepting submissions right now.`
Causa	O formulário está pausado no painel.
Correção	Retome o formulário.

403 captcha_failed

Mensagem	`The captcha check failed. Please try again.`
Causa	O token do Turnstile está ausente, expirou, já foi usado ou não passou na verificação.
Correção	Obtenha um token novo a cada envio. Com suas próprias chaves, confira se a site key corresponde ao segredo.

403 challenge_required

Mensagem	`Complete the human check, then send the form again.`
Causa	O formulário usa a verificação humana do Ikiform e um envio JSON chegou sem token.
Correção	Chame `challenge(formId)` do SDK e passe o token, ou use `error.challenge_url`. Envios de servidor podem enviar uma chave secreta no lugar.

404 not_found

Mensagem	`Not found.`
Causa	O formulário não existe, foi excluído ou desativado, ou o id ou a rota estão errados. Também é retornado em um `GET` para `/f/<formId>`.
Correção	Copie o endpoint da visão geral do formulário e envie para ele em vez de abri-lo em uma aba.

405 method_not_allowed

Mensagem	`This method is not allowed here.`
Causa	Um preflight do navegador na API REST, que é só de servidor para servidor.
Correção	Chame `/api/v1` a partir do seu backend.

409 idempotency_in_progress

Mensagem	`A request with this idempotency key is still being processed.`
Causa	Uma requisição com esta chave de idempotência ainda está sendo processada.
Correção	Espere um momento e tente de novo com a mesma chave; você vai receber a primeira resposta.

413 payload_too_large

Mensagem	`The submission is too large.`
Causa	O corpo, um nome de campo, um valor ou o número de campos passou do limite. A mensagem diz qual.
Correção	Veja Limites. Divida textos grandes em vários campos ou guarde arquivos em outro lugar e envie um link.

415 unsupported_media_type

Mensagem	`Send the form as urlencoded, multipart or JSON.`
Causa	O `Content-Type` não é urlencoded, multipart nem JSON, ou está ausente.
Correção	Defina `Content-Type: application/json` ao enviar JSON.

415 unsupported_charset

Mensagem	`Only UTF-8 is supported.`
Causa	O corpo não é UTF-8, ou declara outro charset.
Correção	Codifique em UTF-8. Adicione `accept-charset="utf-8"` a formulários HTML antigos.

422 validation_failed

Mensagem	`Some fields are invalid.`
Causa	Os campos falharam na validação. `error.fields` associa ids de campo a mensagens.
Correção	Mostre as mensagens ao lado dos campos. Veja Campos.

422 files_not_supported

Mensagem	`File uploads are not supported yet.`
Causa	O envio contém um arquivo. O upload de arquivos ainda não existe.
Correção	Remova os inputs de arquivo, ou faça upload dos arquivos em outro lugar e envie o link.

422 too_deep

Mensagem	`The JSON body is nested too deeply.`
Causa	O corpo JSON tem mais de 3 níveis de aninhamento, contando o objeto de topo.
Correção	Achate os dados, por exemplo `{ "address_city": "London" }`.

422 idempotency_mismatch

Mensagem	`This idempotency key was already used with a different payload.`
Causa	Esta chave de idempotência já foi usada neste formulário nas últimas 24 horas com campos diferentes.
Correção	Use uma chave nova para dados novos. Mantenha a mesma chave só para novas tentativas idênticas.

429 rate_limited

Mensagem	`Too many requests. Please slow down.`
Causa	Acima de um limite de taxa. `Retry-After` diz quantos segundos esperar.
Correção	Espere e tente de novo. Se visitantes reais atingirem o limite, mude o limite de taxa do formulário.

429 quota_exceeded

Mensagem	`This form isn't accepting submissions right now.`
Causa	O workspace recebeu 2 vezes o seu limite mensal de envios neste mês.
Correção	Faça upgrade, ou espere o próximo mês. Veja Uso mensal.

500 server_error

Mensagem	`Something went wrong on our side.`
Causa	Algo falhou do lado do Ikiform.
Correção	Tente de novo com backoff e uma chave de idempotência. Se continuar acontecendo, informe o `request_id`.

O que não é erro

Spam recebe o mesmo 201 ou redirecionamento de um envio real. Procure-o no filtro de spam do painel.
Um _redirect não permitido é ignorado, e o navegador cai na página de agradecimento hospedada.
Um _replyto que não seja um único endereço de e-mail válido é ignorado.

Novas tentativas

Tente de novo um 429 depois do Retry-After, e 500, 409 ou erros de rede com backoff. Envie uma chave de idempotência para que uma nova tentativa nunca crie um duplicado.
Não repita outros erros 4xx sem mudanças. Corrija a requisição primeiro.