Saltar al contenido principal

Resolución de problemas

Los errores que verás al integrar Neuroon y la solución directa.

401 Unauthorized — token expirado​

Tu Widget Token caducó (TTL: 24 horas).

Solución:

curl -X POST https://api.neuroon.ai/api/shops/$SHOP_ID/widget-token \
  -H "X-Shop-API-Key: $API_KEY"

Cachea el nuevo token y reemplázalo en data-token. Si te pasa repetidamente, programa la rotación cada 23 horas desde tu servidor.

401 Unauthorized — Shop API Key inválida​

Estás llamando a /api/plugin/shops/... con una key que no coincide con el shopId de la URL, o la key no existe.

Verifica:

  1. La key está en el dashboard, en la tienda correcta.
  2. La key empieza por sk_ y tiene 35 caracteres en total.
  3. NO mezclas Producción (api.neuroon.ai) con Desarrollo (dev-api.neuroon.ai).

403 Forbidden — Origin mismatch​

El navegador está cargando el widget desde un dominio que no coincide con la URL registrada de tu tienda.

Solución:

  1. Ve a https://neuroon.ai/dashboard → tu tienda → Configuración y comprueba que URL apunta a tu dominio real.
  2. Si tienes múltiples dominios (staging.tutienda.com + tutienda.com), contacta a soporte para añadir orígenes adicionales.

403 Forbidden — Domain not verified​

Tu dominio aún no está verificado.

Solución:

  1. Dashboard → tu tienda → Verificar dominio → sigue las instrucciones (añade el meta tag o registro DNS).
  2. Vuelve a llamar a /api/plugin/shops/{shopId}/verify.

429 Too Many Requests​

Has superado el rate limit de un endpoint específico.

Solución: lee el header Retry-After (en segundos) y espera. Implementa backoff exponencial:

async function withRetry(fn, max = 3) {
  for (let i = 0; i < max; i++) {
    const res = await fn();
    if (res.status !== 429) return res;
    const wait = (parseInt(res.headers.get('retry-after')) || 2 ** i) * 1000;
    await new Promise(r => setTimeout(r, wait));
  }
  throw new Error('Rate limit exceeded after retries');
}

Ver Rate limits para los valores exactos por endpoint.

CORS error en el navegador​

Tu frontend está llamando directamente a /api/plugin/shops/... desde el navegador. Eso no funciona y no debe funcionar: el endpoint del plugin es server-to-server.

Solución: mueve esa llamada a tu backend. El navegador solo debe llamar a /api/widget/* con X-Widget-Token. Para sincronizar productos, generar tokens y trackear conversiones server-side, todo va desde tu servidor.

Widget no aparece / pantalla vacía​

Lo primero, abre la consola del navegador.

SíntomaCausaFix
data-token está vacíoTu plantilla no imprime el tokenImprime el token desde tu servidor con la sintaxis correcta de tu motor (<%= token %>, {{ token }}, ${token})
Failed to load https://cdn.neuroon.ai/widget.jsCSP bloquea el CDNAñade script-src https://cdn.neuroon.ai y connect-src https://api.neuroon.ai a tu Content-Security-Policy
Widget carga pero búsquedas dan 0 resultadosProductos aún no indexadosEspera 2-5 segundos tras el sync. Si pasados 30 s sigue vacío, verifica que el 200 OK del sync incluyó newProducts: N con N > 0

Producto sincronizado pero no aparece en búsqueda​

VerificaciónCómo
Sync devolvió newProducts > 0 y failed: 0Mira la respuesta JSON del POST products/sync
Han pasado más de 5 s desde el 200 OKEspera. La indexación es eventual (típicamente 2-5 s)
El externalId y url no son vacíosEl backend rechaza productos con campos requeridos vacíos

Si todo es correcto y no aparece en 30 s, contacta a soporte con tu shopId y el externalId afectado.

Errores en el endpoint de sync (400)​

Si recibes 400 Bad Request al sincronizar, el body de respuesta incluye errors con el detalle:

{
  "totalReceived": 2,
  "newProducts": 1,
  "failed": 1,
  "errors": [
    { "externalId": "abc-123", "error": "name must not be blank" }
  ]
}

Validaciones obligatorias:

  • externalId no vacío
  • name no vacío, máximo 512 caracteres (@Size(max=512) en ShopRequestDTO.java:72)
  • price ≥ 0
  • currency ISO 4217 (3 letras: EUR, USD, MXN...)
  • url válida

Sigues atascado​

Soporte — incluye en tu mensaje:

  • shopId
  • Endpoint que llamabas
  • Body de la request (sin secrets)
  • Status code y body de la respuesta
  • Hora aproximada (UTC) para que podamos correlacionar.
Última actualización en