Errores

Cada código de error que devuelve Ikiform, con su estado HTTP, su causa y su solución.

Los envíos de formularios y la API REST comparten un mismo formato de error. Las peticiones JSON lo reciben con el estado HTTP correspondiente; los envíos de formularios del navegador reciben una página de error alojada con el mismo mensaje y estado.

El formato de error

Error

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

error.code es estable; usa ese valor para decidir. error.message es inglés sencillo pensado para personas y puede cambiar.
error.fields aparece en los errores de validación, indexado por id de campo, cada uno con una lista de mensajes. Los errores sobre el cuerpo completo usan la clave _form.
error.challenge_url aparece en challenge_required.
request_id coincide con la cabecera X-Request-Id que lleva cada respuesta.
Las respuestas con límite de frecuencia llevan Retry-After en segundos. Ambas cabeceras se pueden leer desde el código del navegador.

Códigos

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

400 invalid_body

Mensaje	`The request body could not be read.`
Causa	JSON o multipart mal formado, un array o una cadena JSON en lugar de un objeto, o una clave de idempotencia de más de 255 caracteres.
Solución	Envía un único objeto JSON, o deja que el navegador o `FormData` construyan el cuerpo.

400 invalid_request

Mensaje	`The request is invalid.`
Causa	`limit`, `status`, `form_id` o `cursor` no es válido. El mensaje indica el parámetro.
Solución	Usa `limit` de 1 a 100, `status` `received` o `spam`, un id `frm_` real y los cursores exactamente como se devolvieron.

401 unauthorized

Mensaje	`A valid API key is required.`
Causa	No hay cabecera `Authorization`, no es un token Bearer, o la clave es desconocida, está revocada o caducada.
Solución	Envía `Authorization: Bearer ik_sk_...` con una clave secreta activa.

402 plan_required

Mensaje	`This form isn't accepting submissions right now.`
Causa	El espacio de trabajo no tiene un plan activo. Esto solo puede pasar cuando se active la facturación.
Solución	Elige un plan en el panel, en Settings.

403 forbidden

Mensaje	`You do not have access to this resource.`
Causa	La clave de API está mal formada, pertenece a otro espacio de trabajo, es publicable en la API REST o le falta el permiso necesario.
Solución	Usa una clave secreta de este espacio de trabajo con el permiso que indica el mensaje.

403 origin_not_allowed

Mensaje	`This form does not accept submissions from this site.`
Causa	El envío vino de un sitio fuera de los dominios permitidos del formulario y el formulario rechaza las discrepancias, o se usó una clave publicable desde un dominio que no está en la clave.
Solución	Añade el sitio a Allowed domains o a los dominios de la clave. Para envíos desde servidor, usa una clave secreta.

403 form_paused

Mensaje	`This form is not accepting submissions right now.`
Causa	El formulario está en pausa en el panel.
Solución	Reanuda el formulario.

403 captcha_failed

Mensaje	`The captcha check failed. Please try again.`
Causa	El token de Turnstile falta, caducó, ya se usó o no pasó la verificación.
Solución	Obtén un token nuevo en cada envío. Con tus propias claves, comprueba que la clave de sitio corresponde al secreto.

403 challenge_required

Mensaje	`Complete the human check, then send the form again.`
Causa	El formulario usa la verificación humana de Ikiform y llegó un envío JSON sin token.
Solución	Llama a `challenge(formId)` del SDK y pasa el token, o usa `error.challenge_url`. Los envíos desde servidor pueden enviar una clave secreta en su lugar.

404 not_found

Mensaje	`Not found.`
Causa	El formulario no existe, se eliminó o se desactivó, o el id o la ruta son incorrectos. También se devuelve ante un `GET` a `/f/<formId>`.
Solución	Copia el endpoint desde el resumen del formulario y envía a él en lugar de abrirlo en una pestaña.

405 method_not_allowed

Mensaje	`This method is not allowed here.`
Causa	Un preflight del navegador en la API REST, que es solo de servidor a servidor.
Solución	Llama a `/api/v1` desde tu backend.

409 idempotency_in_progress

Mensaje	`A request with this idempotency key is still being processed.`
Causa	Todavía se está procesando una petición con esta clave de idempotencia.
Solución	Espera un momento y reintenta con la misma clave; recibirás la primera respuesta.

413 payload_too_large

Mensaje	`The submission is too large.`
Causa	El cuerpo, un nombre de campo, un valor o el número de campos supera su límite. El mensaje indica cuál.
Solución	Consulta Límites. Reparte el texto largo entre varios campos, o guarda los archivos en otro lugar y envía un enlace.

415 unsupported_media_type

Mensaje	`Send the form as urlencoded, multipart or JSON.`
Causa	El `Content-Type` no es urlencoded, multipart ni JSON, o falta.
Solución	Define `Content-Type: application/json` cuando envíes JSON.

415 unsupported_charset

Mensaje	`Only UTF-8 is supported.`
Causa	El cuerpo no es UTF-8, o declara otro charset.
Solución	Codifica en UTF-8. Añade `accept-charset="utf-8"` a los formularios HTML antiguos.

422 validation_failed

Mensaje	`Some fields are invalid.`
Causa	Hay campos que no pasaron la validación. `error.fields` relaciona los ids de campo con los mensajes.
Solución	Muestra los mensajes junto a los campos. Consulta Campos.

422 files_not_supported

Mensaje	`File uploads are not supported yet.`
Causa	El envío contiene un archivo. La subida de archivos aún no existe.
Solución	Quita los inputs de archivo, o sube los archivos a otro lugar y envía el enlace.

422 too_deep

Mensaje	`The JSON body is nested too deeply.`
Causa	El cuerpo JSON tiene más de 3 niveles de anidamiento, contando el objeto principal.
Solución	Aplana los datos, por ejemplo `{ "address_city": "London" }`.

422 idempotency_mismatch

Mensaje	`This idempotency key was already used with a different payload.`
Causa	Esta clave de idempotencia ya se usó en este formulario en las últimas 24 horas con campos distintos.
Solución	Usa una clave nueva para datos nuevos. Mantén la misma clave solo para reintentos idénticos.

429 rate_limited

Mensaje	`Too many requests. Please slow down.`
Causa	Se superó un límite de frecuencia. `Retry-After` indica cuántos segundos esperar.
Solución	Espera y reintenta. Si les pasa a visitantes reales, cambia el límite de frecuencia del formulario.

429 quota_exceeded

Mensaje	`This form isn't accepting submissions right now.`
Causa	El espacio de trabajo recibió este mes el doble de su límite mensual de envíos.
Solución	Mejora tu plan o espera al mes siguiente. Consulta Uso mensual.

500 server_error

Mensaje	`Something went wrong on our side.`
Causa	Algo falló del lado de Ikiform.
Solución	Reintenta con backoff y una clave de idempotencia. Si sigue pasando, indica el `request_id`.

Lo que no son errores

El spam recibe el mismo 201 o la misma redirección que un envío real. Búscalo en el filtro de spam del panel.
Un _redirect no permitido se ignora y el navegador llega a la página de agradecimiento alojada.
Un _replyto que no es una única dirección de email válida se ignora.

Reintentos

Reintenta un 429 después de Retry-After, y los 500, 409 o errores de red con backoff. Envía una clave de idempotencia para que un reintento nunca cree un duplicado.
No reintentes otros errores 4xx sin cambios. Corrige antes la petición.