Solución de problemas
Diagnostica y resuelve problemas comunes sin soporte.
Red / tiempo de conexión agotado
- •Cortafuegos bloqueando HTTPS saliente a api.whisperx.ai
- •Problemas de enrutamiento VPN
- •Configuración incorrecta de DNS
Prueba la conectividad paso a paso:
# 1. DNS resolution nslookup api.whisperx.ai # 2. TCP port 443 nc -zv api.whisperx.ai 443 # 3. HTTPS GET curl -v --max-time 5 "https://api.whisperx.ai/api/tags/trending"
Si el paso 1 falla: comprueba la configuración DNS. Si el paso 2 falla: el cortafuegos bloquea el puerto 443 — contacta al administrador de red. Si el paso 3 falla: problema TLS — asegúrate de tener certificados raíz actualizados.
Resultados vacíos
- •La consulta es demasiado específica o de nicho
- •Filtro de etiquetas demasiado restrictivo
- •La fecha since es demasiado reciente
- •El filtro de sector excluye intel relevante
Prueba consultas progresivamente más amplias:
# Remove tag filter curl "https://api.whisperx.ai/api/intel?q=OpenAI&limit=10" # Remove sector filter curl "https://api.whisperx.ai/api/intel?q=layoff&limit=10" # Extend time window (no since filter) curl "https://api.whisperx.ai/api/intel?q=funding&limit=10" # Try trending tags to see what's active curl "https://api.whisperx.ai/api/tags/trending?limit=20"
Los resultados vacíos no son un error — significan que ninguna intel coincide con tus filtros ahora. La plataforma crece cada día; inténtalo mañana o amplía la búsqueda.
429 — Límite de tasa
- •Más de 60 llamadas API por minuto desde la misma IP
- •Bucle automatizado sin pausa entre peticiones
- •Múltiples agentes compartiendo una conexión
Reduce la frecuencia de peticiones:
- • Espera 60 segundos antes de reintentar
- • Añade sleep 2 entre peticiones en scripts
- • Reduce el parámetro limit (prueba 5–10 en vez de 50)
- • Guarda en caché las etiquetas en tendencia — cambian lentamente, no es necesario consultar cada minuto
Si necesitas límites de tasa más altos para casos de uso en producción, contáctanos.
5xx — Error del servidor
- •Error transitorio en el servidor de origen
- •Arranque en frío del worker bajo carga
- •Base de datos temporalmente no disponible
Estrategia de reintento:
# Retry once after 10 seconds sleep 10 && curl "https://api.whisperx.ai/api/intel?q=test&limit=1" # If 5xx persists, fall back to trending tags (lighter endpoint) curl "https://api.whisperx.ai/api/tags/trending?limit=10"
Si los errores persisten más de 5 minutos, consulta whisperx.ai para actualizaciones de estado. La mayoría de los problemas se resuelven en minutos.
Respuestas lentas / tiempos de espera
- •Búsqueda semántica activada (escaneo completo de tabla — muy costoso)
- •Parámetro limit demasiado alto (>50)
- •Latencia de red al edge de Cloudflare
Asegúrate de que la búsqueda semántica está desactivada y reduce el limit:
# Good: keyword search, compact mode, small limit curl "https://api.whisperx.ai/api/intel?q=OpenAI&mode=compact&limit=10" # Bad: semantic search (avoid — full-table scan) # /api/intel?semantic=... ← do NOT use this
La Skill de WhisperX desactiva automáticamente la búsqueda semántica. Si llamas a la API directamente, nunca uses el parámetro semantic en producción.
Skill no encontrada / herramientas no cargando
- •Skill instalada en el directorio incorrecto
- •SKILL.md falta o está vacío
- •Scripts de shell sin permisos de ejecución
- •Variable de entorno WHISPERX_BASE_URL configurada incorrectamente
Verifica tu instalación:
# Check skill files exist ls ~/.claude/skills/whisperx/ # Expected: SKILL.md tools/ ls ~/.claude/skills/whisperx/tools/ # Expected: search.sh get.sh trending.sh trends.sh connections.sh export.sh # Check scripts are executable ls -la ~/.claude/skills/whisperx/tools/*.sh # Should show -rwxr-xr-x permissions # Fix permissions if needed chmod +x ~/.claude/skills/whisperx/tools/*.sh # Quick smoke test bash ~/.claude/skills/whisperx/tools/trending.sh 5
¿Sigue sin funcionar? Vuelve a ejecutar la instalación desde la Guía de inicio rápido.
Generar informe de diagnóstico
Si sigues atascado, ejecuta esto para generar un paquete de diagnóstico compartible (sin datos sensibles):
echo "=== WhisperX Diagnostic ===" && \
echo "Date: $(date -u)" && \
echo "OS: $(uname -a)" && \
echo " && \
echo "--- Connectivity ---" && \
curl -s -o /dev/null -w "HTTP %{http_code} | Time %{time_total}s" \
"https://api.whisperx.ai/api/tags/trending?limit=1" && \
echo " && \
echo "--- Skill files ---" && \
ls -la ~/.claude/skills/whisperx/tools/ 2>/dev/null || echo "Skill not installed"Pega el resultado al solicitar soporte. No incluye tu IP, consultas ni claves.