Troubleshooting

Diagnose and fix common issues without support.

Network / connection timeout

Symptom: curl hangs, connection refused, or DNS resolution fails
Possible causes
  • •Network firewall blocking outbound HTTPS to api.whisperx.ai
  • •VPN routing issues
  • •DNS misconfiguration
Fix

Test connectivity step by step:

# 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"

If step 1 fails: check your DNS settings. If step 2 fails: firewall is blocking port 443 — contact your network admin. If step 3 fails: TLS issue — ensure your system has up-to-date root certificates.

Empty results

Symptom: Search returns { "data": [] }
Possible causes
  • •Query is too specific or niche
  • •Tag filter too restrictive
  • •since date is too recent
  • •Sector filter excludes matching intel
Fix

Try progressively broader queries:

# 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"

Empty results are not an error — they mean no intel matches your filters right now. The platform grows daily; try again tomorrow or broaden your search.

429 — Rate limited

Symptom: HTTP 429 or error message mentioning rate limit
Possible causes
  • •More than 60 API calls per minute from the same IP
  • •Automated loop with no delay between requests
  • •Multiple agents sharing one connection
Fix

Back off and reduce frequency:

  • • Wait 60 seconds before retrying
  • • Add sleep 2 between requests in scripts
  • • Reduce limit parameter (try 5–10 instead of 50)
  • • Cache trending tags — they change slowly, no need to poll every minute

If you need higher rate limits for production use cases, contact us.

5xx — Server error

Symptom: HTTP 500, 502, or 503 response
Possible causes
  • •Transient upstream error
  • •Worker cold start under load
  • •Database temporarily unavailable
Fix

Retry strategy:

# 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"

If errors persist for more than 5 minutes, check whisperx.ai for status updates. Most issues resolve within minutes.

Slow responses / timeouts

Symptom: Requests take more than 5 seconds, or tool calls time out in OpenClaw
Possible causes
  • •Semantic search enabled (full-table scan — very expensive)
  • •limit set too high (>50)
  • •Network latency to Cloudflare edge
Fix

Ensure semantic search is disabled and lower your 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

The WhisperX Skill automatically disables semantic search. If you're calling the API directly, never use the semantic parameter in production.

Skill not found / tools not loading

Symptom: OpenClaw doesn't recognize whisperx tools or can't find SKILL.md
Possible causes
  • •Skill installed in wrong directory
  • •SKILL.md missing or empty
  • •Shell scripts not executable
  • •WHISPERX_BASE_URL environment variable set incorrectly
Fix

Verify your installation:

# 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

Still not working? Re-run the install from the Quickstart guide.

Generate a diagnostic report

If you're still stuck, run this to generate a shareable diagnostic bundle (no sensitive data):

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"

Paste the output when requesting support. It does not include your IP, queries, or keys.

← OverviewQuickstart