> ## Documentation Index
> Fetch the complete documentation index at: https://developers.flowestate.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Solución de problemas

> Errores comunes, qué significan y cómo arreglarlos.

| 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](/es/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](/es/api-reference/leads#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](/es/webhooks#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](/es/webhooks#prevencion-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:

1. El **cuerpo completo de la respuesta** — siempre lleva `error.code` y `error.message`.
2. El **timestamp** del request (UTC, precisión de segundos basta).
3. El **endpoint** y **método** (`POST /api/v1/leads`, etc.).
4. Para problemas de webhooks, el valor del header **`X-FlowEstate-Delivery`**.
5. 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](mailto:soporte@flowestate.app).

## Salud e incidentes

Revisa [status.flowestate.app](https://status.flowestate.app) antes de debugear a fondo una caída. Si hay una ventana de mantenimiento planificada, respuestas `503` intermitentes son esperadas.