Errores comunes

Recopilación de errores frecuentes con su causa y solución. Para la lista completa de códigos del API, ver API > Errores.

"El buscador devuelve 0 resultados"

Causa 1: el item no esta en stock

Por defecto solo se muestran items con in_stock=true. Si tu cliente busca algo que esta agotado, no aparece.

Solución: o re-stockeas, o pasas filter=in_stock=* en la petición para incluir agotados.

Causa 2: no se indexa la descripción

Si solo indexas el name y el cliente busca por ingrediente / categoría / atributo (que esta en la descripción), no encontrara.

Solución: incluye description (HTML strippeado) en cada item. Mibizum lo indexa con peso adecuado.

Causa 3: el sinónimo es 1 token a N tokens

Caso muy comun: el cliente busca aceitelavanda (sin espacio), tu sinónimo es aceitelavanda -> "aceite lavanda". No funciona.

Solución: ver Guía: Sinónimos 1 a N.

Causa 4: el motor no tiene los sinónimos sincronizados

Los sinónimos viven en BD pero el motor no los conoce.

Solución: ver Guía: Sincronización BD - motor. Panel > Sinónimos > Re-sincronizar al motor.

"El widget no aparece"

Causa 1: el script tag no carga

Verifica que el <script> esta antes de </body> y los atributos data-mibizum-tenant + data-mibizum-public-key son correctos.

// En consola del navegador
window.__mibizum
// undefined = no cargo

Causa 2: Content Security Policy bloquea

Si tu tienda tiene CSP estricto, añade:

script-src 'self' https://cdn.mibizum.io;
connect-src 'self' https://api.mibizum.io;
img-src 'self' data: https://cdn.mibizum.io;

Causa 3: el tenant slug es incorrecto

Verifica el slug en Ajustes > General del panel. Es case-sensitive.

"Smart Mibizum no aprende nada"

Causa 1: pocas sesiones distintas

Por defecto, Smart requiere que un par (failed, rescue) aparezca en al menos 3 sesiones distintas antes de aprenderlo. Si tu tienda tiene poco tráfico, baja learning_min_sessions a 1 o 2 en Ajustes > Smart.

Causa 2: modo off

Verifica que learning_mode no este off. En el panel: Ajustes > Aprendizaje IA > Modo.

Causa 3: queries demasiado largas

Si tus clientes pegan frases largas (>20 chars), Smart las descarta como "no aprendibles". Esto es por diseño (ver Guía: Recetas vs typos). Ajusta smart_max_query_length si tu negocio tiene terminos legitimos largos.

Causa 4: la API key Anthropic no esta configurada

Smart necesita acceso al modelo IA. Si tu cuenta es nueva o has rotado la key, verifica en Ajustes > Integraciones > IA que esta cargada.

"El sync de catalogo falla"

Causa 1: payload demasiado grande

Lotes de >1000 items pueden hacer timeout. Pagina en lotes de 500.

Causa 2: campos invalidos

El validator del API es estricto. Errores tipicos:

• price como string (debe ser número).
• categories como string (debe ser array de strings).
• id con caracteres no validos (solo [a-zA-Z0-9_-]).

Mira el response del POST para ver el detalle.

Causa 3: API key privada incorrecta

Si usas mb_pk_* (publica) en lugar de mb_sk_* (privada), recibes 403 forbidden_scope. Verifica en tu código backend.

"Rate limited" en producción

Si recibes 429 rate_limited regularmente:

1. Verifica que no llamas desde el navegador con la privada (cada cliente cuenta como una llamada distinta multiplicada por N clientes activos).
2. Verifica que tienes debouncing en el input del buscador (default 150ms desde el panel).
3. Si tu volumen es alto y el límite estándar de 300/min no basta, contacta soporte para subirlo.

"El panel no me deja login"

Causa 1: cookies bloqueadas

El panel usa cookies httpOnly para la sesión. Si el navegador las bloquea (modo incognito + ITP, extensiones), no podras login. Prueba en otro navegador.

Causa 2: cuenta no verificada

Tras signup necesitas verificar el email. Revisa spam y reenvia desde la pantalla de login.

Causa 3: rate limit en login

Tras varios intentos fallidos, hay backoff progresivo. Espera 5 minutos y reintenta.