Common Issues

This guide helps you troubleshoot the most common issues with SupaScan platform and API.

API Authentication Issues

Error: "Invalid API key"

Symptoms:

{
  "error": "INVALID_API_KEY",
  "message": "Invalid API key",
  "status": 401
}

Solutions:

  1. Verify API key format:

    echo $SUPASCAN_API_KEY | grep -E "^sk_[a-zA-Z0-9]{32}$"

  2. Check API key in SupaScan portal:

    • Log into SupaScan Portal
    • Go to API Keys section
    • Verify key is active and not expired
    • Generate new key if needed

  3. Check environment variables:

    # Ensure no extra spaces
echo "API_KEY=$SUPASCAN_API_KEY" >> .env

  4. Verify key permissions:

    • Check if key has required permissions for the endpoint
    • Ensure key is not rate limited

Error: "Rate limit exceeded"

Symptoms:

{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Rate limit exceeded. Please try again later",
  "status": 429,
  "retry_after": 60
}

Solutions:

  1. Check your current usage:

    curl -H "Authorization: Bearer $SUPASCAN_API_KEY" \
     https://api.supascan.xyz/v1/usage

  2. Implement exponential backoff:

    async function apiCallWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);
      if (response.status === 429) {
        const retryAfter = response.headers.get('Retry-After');
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
      return response;
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await new Promise(resolve => setTimeout(resolve, Math.pow(2, i) * 1000));
    }
  }
}

  3. Upgrade your plan if you need higher limits

Error: "Insufficient permissions"

Symptoms:

{
  "error": "INSUFFICIENT_PERMISSIONS",
  "message": "Insufficient permissions for this operation",
  "status": 403
}

Solutions:

  1. Check API key permissions:

    • Log into SupaScan portal
    • Review key permissions
    • Enable required features

  2. Verify endpoint access:

    • Some endpoints require premium access
    • Check your subscription plan

ClickHouse Database Issues

Error: "Connection refused"

Symptoms:

Error: connect ECONNREFUSED 127.0.0.1:9000
Error: ClickHouse server is not responding

Solutions:

  1. Check ClickHouse status:

    sudo systemctl status clickhouse-server

  2. Start ClickHouse service:

    sudo systemctl start clickhouse-server
sudo systemctl enable clickhouse-server

  3. Check configuration:

    # Check config file
clickhouse-client --config-file /etc/clickhouse-server/config.xml --query "SELECT 1"

  4. Verify port accessibility:

    netstat -tlnp | grep 9000
telnet localhost 9000

Error: "Query timeout"

Symptoms:

{
  "error": "QUERY_TIMEOUT",
  "message": "Query timeout. Please try a simpler query",
  "status": 408
}

Solutions:

  1. Optimize your query:

    -- Instead of scanning all data
SELECT * FROM transactions WHERE slot > 123456789;

-- Use time-based filters
SELECT * FROM transactions 
WHERE block_time > now() - INTERVAL 1 HOUR
AND slot > 123456789;

  2. Add LIMIT clause:

    SELECT * FROM token_transfers 
WHERE token_mint = 'So11111111111111111111111111111111111111112'
ORDER BY block_time DESC
LIMIT 1000;

  3. Use materialized views:

    -- Use pre-aggregated data
SELECT * FROM daily_token_volume 
WHERE token_mint = 'So11111111111111111111111111111111111111112'
AND date >= '2024-01-01';

  4. Check query complexity:

    • Avoid complex JOINs on large tables
    • Use appropriate indexes
    • Consider breaking complex queries into smaller ones

Error: "Memory limit exceeded"

Symptoms:

Error: Memory limit (for query) exceeded: would use 9.37 GiB (attempt to allocate chunk of 4200000 bytes)

Solutions:

  1. Reduce query scope:

    -- Instead of processing all data
SELECT token_mint, sum(amount) FROM token_transfers;

-- Process in time chunks
SELECT token_mint, sum(amount) 
FROM token_transfers 
WHERE block_time > now() - INTERVAL 1 DAY;

  2. Use sampling:

    SELECT token_mint, sum(amount) 
FROM token_transfers SAMPLE 0.1
GROUP BY token_mint;

  3. Optimize GROUP BY:

    -- Use appropriate data types
SELECT token_mint, sum(amount) as total_amount
FROM token_transfers
GROUP BY token_mint
ORDER BY total_amount DESC
LIMIT 100;

Solana Indexing Issues

Error: "RPC request failed"

Symptoms:

Error: connect ETIMEDOUT
Error: Request failed with status code 429
Error: 502 Bad Gateway

Solutions:

  1. Test Solana RPC endpoint:

    curl -X POST $SOLANA_RPC_URL \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"getSlot","params":[],"id":1}'

  2. Check network connectivity:

    ping -c 4 8.8.8.8
nslookup api.mainnet-beta.solana.com

  3. Try alternative RPC endpoints:

    # Add multiple endpoints for failover
SOLANA_RPC_URLS="https://api.mainnet-beta.solana.com,https://solana-api.projectserum.com"

  4. Check RPC rate limits:

    • Some RPC providers have strict rate limits
    • Consider upgrading to premium RPC access
    • Implement request queuing

Error: "Block parsing failed"

Symptoms:

Error: Failed to parse block 123456789
Error: Invalid transaction format
Error: Missing required fields

Solutions:

  1. Check block data integrity:

    # Verify block exists on blockchain
curl -X POST $SOLANA_RPC_URL \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"getBlock","params":[123456789],"id":1}'

  2. Update parser version:

    npm update @supascan/parser

  3. Check for Solana network upgrades:

    • New instruction types may require parser updates
    • Check Solana changelog for breaking changes

  4. Enable debug logging:

    export LOG_LEVEL=debug
# Check logs for detailed error information

Error: "Indexing lag detected"

Symptoms:

Warning: Indexing lag detected: 5 minutes behind
Error: Slot sync check failed

Solutions:

  1. Check indexing performance:

    # Monitor indexing speed
curl -H "Authorization: Bearer $SUPASCAN_API_KEY" \
     https://api.supascan.xyz/v1/status

  2. Optimize ClickHouse performance:

    -- Check table sizes
SELECT table, formatReadableSize(sum(bytes)) as size
FROM system.parts
WHERE database = 'supascan'
GROUP BY table;

  3. Scale up resources:

    • Increase ClickHouse cluster size
    • Add more indexing workers
    • Optimize database queries

  4. Check network conditions:

    • RPC endpoint response times
    • Network latency to Solana nodes
    • Bandwidth limitations

Webhook and Notification Issues

Error: "Webhook delivery failed"

Symptoms:

{
  "error": "WEBHOOK_DELIVERY_FAILED",
  "message": "Failed to deliver webhook to https://your-app.com/webhook",
  "webhook_id": "wh_1234567890abcdef"
}

Solutions:

  1. Check webhook endpoint:

    # Test webhook endpoint manually
curl -X POST https://your-app.com/webhook \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

  2. Verify endpoint accessibility:

    • Ensure endpoint is publicly accessible
    • Check SSL certificate validity
    • Verify firewall rules

  3. Check webhook configuration:

    # Get webhook details
curl -H "Authorization: Bearer $SUPASCAN_API_KEY" \
     https://api.supascan.xyz/v1/webhooks/wh_1234567890abcdef

  4. Implement retry logic:

    // Your webhook endpoint should handle retries
app.post('/webhook', (req, res) => {
  try {
    // Process webhook
    processWebhook(req.body);
    res.status(200).json({ success: true });
  } catch (error) {
    // Return 5xx for retry, 4xx for permanent failure
    res.status(500).json({ error: 'Processing failed' });
  }
});

Error: "Webhook filter evaluation failed"

Symptoms:

Error: Failed to evaluate webhook filter
Error: Invalid filter expression

Solutions:

  1. Check filter syntax:

    {
  "filters": {
    "token_name_contains": ["PEPE", "DOGE"],
    "min_initial_supply": 1000000000,
    "dex_protocols": ["raydium", "meteora"]
  }
}

  2. Validate filter logic:

    • Ensure all filter fields are supported
    • Check data types match expected values
    • Test filters with sample data

  3. Simplify complex filters:

    // Instead of complex nested filters
{
  "filters": {
    "token_name_contains": ["PEPE"],
    "min_liquidity_usd": 10000
  }
}

Error: "Webhook rate limit exceeded"

Symptoms:

{
  "error": "WEBHOOK_RATE_LIMIT_EXCEEDED",
  "message": "Webhook rate limit exceeded",
  "retry_after": 300
}

Solutions:

  1. Check webhook limits:

    curl -H "Authorization: Bearer $SUPASCAN_API_KEY" \
     https://api.supascan.xyz/v1/webhooks/usage

  2. Implement cooldown periods:

    {
  "notification_settings": {
    "cooldown_minutes": 10,
    "max_notifications_per_hour": 50
  }
}

  3. Optimize filter specificity:

    • More specific filters = fewer notifications
    • Use multiple webhooks for different criteria
    • Batch similar notifications

Data Quality Issues

Error: "Inconsistent data detected"

Symptoms:

Warning: Data inconsistency detected in slot 123456789
Error: Token transfer amount mismatch

Solutions:

  1. Verify data integrity:

    -- Check for duplicate transactions
SELECT signature, COUNT(*) as count
FROM transactions
GROUP BY signature
HAVING count > 1;

  2. Re-index problematic data:

    # Trigger re-indexing for specific slot range
curl -X POST -H "Authorization: Bearer $SUPASCAN_API_KEY" \
     https://api.supascan.xyz/v1/admin/reindex \
     -d '{"start_slot": 123456780, "end_slot": 123456790}'

  3. Check parser version:

    • Ensure you're using the latest parser
    • Some data inconsistencies may be due to parser bugs

Error: "Missing token metadata"

Symptoms:

Warning: Token metadata not found for mint So11111111111111111111111111111111111111112
Error: Token name/symbol not available

Solutions:

  1. Check token metadata service:

    curl -H "Authorization: Bearer $SUPASCAN_API_KEY" \
     https://api.supascan.xyz/v1/tokens/So11111111111111111111111111111111111111112

  2. Trigger metadata refresh:

    curl -X POST -H "Authorization: Bearer $SUPASCAN_API_KEY" \
     https://api.supascan.xyz/v1/tokens/So11111111111111111111111111111111111111112/refresh

  3. Check token program:

    • Some tokens may not have metadata
    • Verify token is a valid SPL token

SupaApps Issues

Error: "SupaApp not responding"

Symptoms:

Error: Wallet Profiler is not responding
Error: KOL Watch service unavailable

Solutions:

  1. Check SupaApp status:

    curl -H "Authorization: Bearer $SUPASCAN_API_KEY" \
     https://api.supascan.xyz/v1/supapps/status

  2. Restart specific SupaApp:

    curl -X POST -H "Authorization: Bearer $SUPASCAN_API_KEY" \
     https://api.supascan.xyz/v1/supapps/wallet-profiler/restart

  3. Check resource usage:

    • SupaApps may be resource-intensive
    • Consider upgrading your plan for better performance

Error: "Analysis timeout"

Symptoms:

Error: Wallet analysis timeout after 30 seconds
Error: Pattern detection failed

Solutions:

  1. Simplify analysis parameters:

    {
  "wallet_address": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
  "analysis_depth": "basic",  // Instead of "comprehensive"
  "time_range": "7d"          // Instead of "30d"
}

  2. Use pagination for large datasets:

    curl -H "Authorization: Bearer $SUPASCAN_API_KEY" \
     "https://api.supascan.xyz/v1/wallets/9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM/transactions?limit=100&offset=0"

  3. Check wallet activity level:

    • Very active wallets may require more processing time
    • Consider filtering by time range

Performance Issues

Error: "API response slow"

Symptoms:

Warning: API response time > 5 seconds
Error: Request timeout

Solutions:

  1. Check API status:

    curl https://api.supascan.xyz/v1/status

  2. Use appropriate endpoints:

    # Use REST API for simple queries
curl -H "Authorization: Bearer $SUPASCAN_API_KEY" \
     https://api.supascan.xyz/v1/tokens/So11111111111111111111111111111111111111112

# Use SQL API for complex analytics
curl -X POST -H "Authorization: Bearer $SUPASCAN_API_KEY" \
     https://api.supascan.xyz/v1/sql/query \
     -d '{"query": "SELECT * FROM token_transfers LIMIT 100"}'

  3. Implement caching:

    // Cache frequently accessed data
const cache = new Map();

async function getTokenData(mint) {
  if (cache.has(mint)) {
    return cache.get(mint);
  }
  
  const data = await api.getToken(mint);
  cache.set(mint, data);
  return data;
}

Error: "High memory usage"

Symptoms:

Warning: Memory usage > 80%
Error: Out of memory

Solutions:

  1. Check ClickHouse memory usage:

    SELECT * FROM system.processes
WHERE query LIKE '%your_query%';

  2. Optimize queries:

    -- Use LIMIT to reduce memory usage
SELECT * FROM transactions
WHERE block_time > now() - INTERVAL 1 HOUR
ORDER BY slot DESC
LIMIT 1000;

  3. Scale up resources:

    • Increase ClickHouse cluster memory
    • Add more nodes to the cluster
    • Optimize data partitioning

Quick Fixes

Reset API key

# Generate new API key
curl -X POST -H "Authorization: Bearer $SUPASCAN_API_KEY" \
     https://api.supascan.xyz/v1/keys/regenerate

# Update environment variable
export SUPASCAN_API_KEY="sk_new_key_here"

Clear cache

# Clear application cache
curl -X POST -H "Authorization: Bearer $SUPASCAN_API_KEY" \
     https://api.supascan.xyz/v1/cache/clear

Force re-indexing

# Re-index recent data
curl -X POST -H "Authorization: Bearer $SUPASCAN_API_KEY" \
     https://api.supascan.xyz/v1/admin/reindex \
     -d '{"hours_back": 24}'

Test webhook endpoint

# Test webhook with sample data
curl -X POST https://your-app.com/webhook \
     -H "Content-Type: application/json" \
     -d '{
       "event_type": "test",
       "timestamp": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'",
       "data": {"test": true}
     }'

Getting Help

If these solutions don't work:

  1. Collect diagnostic information:

    # API status
curl https://api.supascan.xyz/v1/status

# Your usage stats
curl -H "Authorization: Bearer $SUPASCAN_API_KEY" \
     https://api.supascan.xyz/v1/usage

# Recent errors
curl -H "Authorization: Bearer $SUPASCAN_API_KEY" \
     https://api.supascan.xyz/v1/logs/errors

  2. Check SupaScan status page:

  3. Contact support:

    • Use the support form in SupaScan portal
    • Include error messages and diagnostic information
    • Provide your API key (for debugging purposes only)

  4. Community support:

    • Join SupaScan Discord community
    • Check GitHub issues for similar problems
    • Share solutions with the community
Previous
Debug Mode
Next
Links & Tools