Errores frecuentes

Esta guía recoge los errores más habituales que puedes encontrar al usar Conviro y cómo solucionarlos.

HTTP 401 -- Unauthorized

Significado: Tu clave de API o tu token de sesión no es válido o ha caducado.

Causas y soluciones:

• La clave de API es incorrecta -- comprueba la clave en Dashboard -> Settings -> API Keys
• La clave de API se ha revocado -- genera una clave nueva y actualiza tu integración
• La sesión ha caducado -- cierra sesión en el panel y vuelve a entrar
• Falta la cabecera Authorization -- asegúrate de que tu petición a la API incluye Authorization: Bearer sk_your_key

HTTP 403 -- Forbidden

Significado: No tienes permiso para acceder a este recurso.

Causas y soluciones:

• Dominio no permitido -- añade el dominio de tu web en Dashboard -> Assistants -> Your Bot -> Channels -> Allowed Domains
• Límite del plan alcanzado -- estás intentando usar una función que no está disponible en tu plan actual (por ejemplo, WhatsApp en Starter)
• Restricción de rol -- puede que tu rol de equipo (Agent) no tenga permiso para esta acción; pídeselo a un Admin o a un Owner
• El bot está inactivo -- activa el bot en Dashboard -> Assistants

HTTP 404 -- Not Found

Significado: El recurso solicitado no existe.

Causas y soluciones:

• Endpoint incorrecto -- consulta la documentación de la API en /developers para ver las URL correctas
• Recurso eliminado -- el chatbot, la sesión o el contacto se ha eliminado
• Error tipográfico en el ID -- comprueba el ID del recurso en la URL de tu petición

HTTP 429 -- Too Many Requests (límite de peticiones)

Significado: Has superado el límite de peticiones a la API de tu plan.

Causas y soluciones:

• Consulta las cabeceras de límite de peticiones en la respuesta:

X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

• Reduce la frecuencia de las peticiones -- añade pausas o agrupa las operaciones
• Mejora tu plan -- los planes superiores tienen límites de peticiones más altos
• Guarda las respuestas en caché -- evita repetir la misma petición una y otra vez

Límites de peticiones por plan:

Errores de CORS

Significado: El navegador está bloqueando una petición de origen cruzado (cross-origin).

Síntoma: Ves en la consola del navegador un error como Access to XMLHttpRequest has been blocked by CORS policy.

Causas y soluciones:

• Dominio del widget no permitido -- añade tu dominio a la lista Allowed Domains
• Contenido mixto -- si el widget se carga por HTTPS, asegúrate de que tu web usa HTTPS (y no HTTP)
• Interferencia del proxy o de la CDN -- comprueba si tu CDN está eliminando las cabeceras CORS

Fallos en la entrega de webhooks

Significado: Conviro ha enviado un webhook, pero tu servidor no ha respondido con un código de estado 2xx.

Causas y soluciones:

• El servidor está caído -- comprueba que tu endpoint de webhook está funcionando y es accesible
• Tiempo de espera agotado -- Conviro espera la respuesta durante 10 segundos. Asegúrate de que tu endpoint responde rápido
• Problema con el certificado SSL -- tu endpoint debe tener un certificado SSL válido (no se aceptan certificados autofirmados)
• Bloqueo del firewall -- añade el rango de IP de Conviro a la lista de permitidos de tu firewall
• URL incorrecta -- verifica la URL del webhook en Dashboard -> Settings -> Webhooks

Política de reintentos: Conviro reintenta los webhooks fallidos 3 veces con espera exponencial (1 min, 5 min, 30 min). Tras 3 fallos, el webhook se marca como erróneo y recibes un aviso por correo electrónico.

Consulta los registros de entrega en Dashboard -> Settings -> Webhooks -> Delivery Log.

Límite de mensajes alcanzado

Significado: Has consumido todos tus mensajes del mes.

Causas y soluciones:

• Free/Starter -- las conversaciones se pausan hasta el siguiente ciclo de facturación. Cambia a un plan superior para tener más mensajes.
• Pro/Growth -- activa la facturación por exceso de uso en Dashboard -> Settings -> Billing para comprar automáticamente bloques de mensajes adicionales.
• Consulta tu consumo -- revisa tu uso en Dashboard -> AI Usage.

Consejos generales

• Revisa siempre la consola del navegador (F12) para detectar errores del lado del cliente.
• En los errores de la API, inspecciona el cuerpo de la respuesta -- suele incluir un mensaje de error descriptivo.
• Consulta la página de estado de Conviro por si hay alguna incidencia o mantenimiento en curso.
• Si no consigues resolver el problema, escribe a [email protected] con los detalles del error, el ID de la petición (si lo tienes) y los pasos para reproducirlo.