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 PLAN_LIMIT_REACHED en POST /leads | La organización está en su tope de leads. | Sube el plan o elimina leads que no uses. Reintentar no sirve. Ver Errores de límite del plan. |
403 FORBIDDEN con “Has alcanzado el número máximo…” | Límite del plan alcanzado en proyectos o webhook endpoints. | 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. |
POST /leads devuelve 201 pero no aparece un lead nuevo | El contacto ya existía, así que la llamada fusionó en vez de crear. | Lee outcome en la respuesta: merged significa que id apunta al lead que ya estaba. |
| No puedo crear a dos personas de la misma empresa | Están compartiendo correo o teléfono, así que resuelven a la misma identidad de contacto. | Dale a cada una su propio correo o teléfono. No hay forma de forzar un duplicado desde la API pública. |
El estimatedValue / notes de un lead no se actualizó tras publicarlo de nuevo | La fusión sólo rellena campos vacíos; nunca pisa uno que ya trae valor. | Usa PUT /leads/{leadId} para sobrescribir a propósito. |
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 reescribiendo los mismos leads | El receptor escribe a FlowEstate sin chequear el source. | Descarta eventos con X-FlowEstate-Source: api. El bucle ya no crea duplicados —las escrituras fusionan— pero igual te quema el rate limit. Ver Prevención de bucles. |
Tu endpoint empieza a recibir muchos más lead.created / lead.assigned que antes | Los canales entrantes (webhooks de leads, Meta lead ads, WhatsApp) eran silenciosos y ahora emiten como cualquier otro canal. | Es lo esperado. Vienen con X-FlowEstate-Source: system. Ver De dónde vienen los eventos de leads. |
| Tu endpoint deja de recibir eventos a mitad de mes, sin ningún error | La organización agotó su cupo mensual de eventos salientes. Los eventos se descartan antes de despacharse, en silencio. | Sacá la organización del plan Free, o reconciliá contra GET /leads. Ver Cupo mensual de eventos. |
Llega un lead.assigned sin un lead.created antes | Un contacto repetido fusionó sobre un lead existente sin asignar, y el round robin se lo asignó después. | Es lo esperado. Manejá los dos eventos de forma independiente. |
| ”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. |