Solución de problemas de solicitudes

Leer un error

Todo rechazo lleva dos cosas: un code para el tipo de fallo, y un details.reason para la causa concreta. Decide según el código; lee el motivo para saber qué arreglar. Cuando ayuda, details también nombra el field ofensor, las claves que se habrían aceptado, o las claves de opción que admite una pregunta de elección.

Los métodos de solicitud usan cuatro códigos: VALIDATION_ERROR (la llamada estaba mal), CONFLICT (la solicitud está en el estado equivocado, o se reutilizó una clave de idempotencia), NOT_FOUND, y UPGRADE_REQUIRED (un límite de plan o la asignación mensual). Llamar demasiado rápido devuelve RATE_LIMITED en su lugar, con retryAfterMs — consulta el límite de frecuencia.

{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "No field with key \"company\".",
    "details": { "reason": "UNKNOWN_FIELD_KEY", "field": "prefill.company", "validKeys": ["company_name", "company_size"] }
  }
}

Motivos que puedes ver

Hacer bien la llamada

Actuar sobre una solicitud existente

La invitación nunca llegó

Abre la solicitud en la página de Solicitudes y lee la cronología. La primera línea de invitación te dice en qué caso estás.

Las invitaciones y los recordatorios comparten un cupo de diez correos al día por formulario y dirección de destinatario, y una solicitud nunca escribe a su destinatario más de nueve veces en toda su vida — una invitación y hasta ocho recordatorios.

El callback nunca aterrizó

La sección Callback del panel de la solicitud muestra la URL y el resultado. Callback fallido tras N intentos significa que formbase lo intentó y se rindió — ocho intentos a lo largo de unas cuatro horas.

1. Comprueba la URL. Se muestra en el panel. La URL de reanudación de una herramienta de flujos de trabajo pertenece a una ejecución, y una ejecución que se borró o se recreó ya no responde en ella.

2. Comprueba qué devolvió tu endpoint. Cualquier cosa fuera de 2xx es un fallo. Un 4xx que no sea 408 ni 429 detiene los reintentos de inmediato — formbase lo interpreta como “tu endpoint rechazó esto”, y reenviar los mismos bytes no puede cambiarlo.

3. Arregla el receptor y luego pulsa Reproducir. El mismo payload sale de nuevo con el mismo id de evento, así que un receptor que desduplica está a salvo.

Otras cosas con las que te puedes topar

• El destinatario dice que el enlace muestra un aviso, no el formulario. La solicitud está en un estado final — completada, expirada o cancelada. Esa es la página de resultado. Crea una nueva solicitud si necesitan otro intento.

• Una automatización dejó de coincidir después de una edición — una respuesta desapareció del callback, o requests.create empezó a rechazar una clave con UNKNOWN_FIELD_KEY. Una clave de campo publicada desapareció: alguien la reescribió, o eliminó la pregunta y añadió una nueva en su lugar. Cambiar el título es seguro; ninguna de esas dos cosas lo es. Escribe la clave antigua en el campo (icono de claves de la barra de herramientas → Claves) y vuelve a publicar. Publicar avisa antes de que esto ocurra — consulta Cuando una clave publicada está a punto de desaparecer.

• El precompletado de una subida de archivo o una firma se rechaza. Eso no puede suministrarlo quien llama — fields.list los marca prefillable: false.

• Aparecieron dos solicitudes para una misma ejecución de flujo. La ejecución se reintentó sin un idempotencyKey. Pasa el id de ejecución como clave.