Troubleshooting

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: vuelve a firmar el token localmente con tu API Key (HMAC) y reemplázalo en data-token. Si te pasa repetidamente, programa la rotación cada 23 horas desde tu servidor. Patrón completo (Node, .NET, Python, PHP) en Recipe · Server-to-server token.

401 Unauthorized — API Key inválida

Estás llamando a /api/integrations/v1/... con una API Key inválida o que no pertenece a tu tienda.

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 (meta tag automático en plugins oficiales, registro DNS TXT en integraciones custom).
2. Pulsa Verificar de nuevo desde el Dashboard.

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/integrations/v1/... desde el navegador. Eso no funciona y no debe funcionar: estos endpoints son 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 y trackear conversiones, todo va desde tu servidor con Authorization: Bearer <api-key>.

Widget no aparece / pantalla vacía

Lo primero, abre la consola del navegador.

Síntoma	Causa	Fix
data-token está vacío	Tu plantilla no imprime el token	Imprime el token desde tu servidor con la sintaxis correcta de tu motor (<%= token %>, {{ token }}, ${token})
Failed to load https://cdn.neuroon.ai/widget.js	CSP bloquea el CDN	Añ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 resultados	Productos aún no indexados	Espera 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ón	Cómo
Sync devolvió newProducts > 0 y failed: 0	Mira la respuesta JSON del POST products/sync
Han pasado más de 5 s desde el 200 OK	Espera. La indexación es eventual (típicamente 2-5 s)
El externalId y url no son vacíos	El 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 200 caracteres
• 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.