Solución de problemas - FlowEstate Developers

Síntoma	Causa probable	Solución
`401 UNAUTHORIZED`	Header `Authorization` ausente o mal formado.	Envía `Authorization: Bearer fe_k_...`, sin prefijos extra ni comillas.
`403 FORBIDDEN` con “Insufficient permissions. Missing scopes: …”	La API key no fue creada con ese scope.	Edita los scopes de la key en el panel, o crea una nueva. Ver Scopes.
`403 FORBIDDEN` con “Has alcanzado el número máximo…”	Límite del plan alcanzado (leads, proyectos, webhook endpoints, etc.).	Sube el plan de la organización o elimina registros que no uses.
`400 VALIDATION_ERROR` en `POST /leads` con “email: Email or phone is required”	Faltan o están vacíos tanto `email` como `phone`.	Provee al menos uno — `""` cuenta como ausente. Ver Crear un lead.
`400 VALIDATION_ERROR` con “email: Invalid email”	El campo email contiene sintaxis de markdown link o caracteres extra.	Envía un valor limpio `usuario@dominio.com`. Ojo con los chats que auto-formatean direcciones.
`404 NOT_FOUND` en un recurso que sabes que existe	El recurso pertenece a una organización diferente a la que está atada al bearer.	Usa una key de la organización correcta. Cada key está scopeada a una organización.
`429` aunque no estés en un loop apretado	Múltiples workers compartiendo una key.	Usa una key por worker — cada uno tiene su propio presupuesto por minuto.
La firma del webhook no coincide	Estás usando JSON parseado en lugar del cuerpo crudo, o el secret está mal.	Hashea los bytes crudos del cuerpo; el secret es el valor devuelto al crear la suscripción. Ver Verificar la firma.
Make / Zapier reintenta el mismo webhook repetidamente	El receptor está devolviendo no-`2xx`.	Devuelve `2xx` aunque ignores el evento (p.ej. `X-FlowEstate-Source: api`).
El receptor entra en bucle creando leads duplicados	El receptor escribe a FlowEstate sin chequear el source.	Descarta eventos con `X-FlowEstate-Source: api`. Ver Prevención de bucles.
”Token is not bound to an organization” en OAuth	Token OAuth de una cuenta de Zapier/Make que no eligió organización todavía.	El usuario final debe completar el flujo de consentimiento / selección de organización una vez en el conector.

Capturando diagnósticos

Cuando abras un ticket de soporte incluye:

El cuerpo completo de la respuesta — siempre lleva error.code y error.message.
El timestamp del request (UTC, precisión de segundos basta).
El endpoint y método (POST /api/v1/leads, etc.).
Para problemas de webhooks, el valor del header X-FlowEstate-Delivery.
Los primeros 8 caracteres de tu API key (fe_k_a1b2c3d4) — no la key completa. Podemos identificar cuál es sin ver el secret.

Envía a soporte@flowestate.app.

Salud e incidentes

Revisa status.flowestate.app antes de debugear a fondo una caída. Si hay una ventana de mantenimiento planificada, respuestas 503 intermitentes son esperadas.

Referencia de enums