Troubleshooting Web App Connection Failures

Connection issues between the SEOvault AI WordPress plugin and the web app can prevent data synchronization and AI features from working. This guide helps you identify and resolve common connection problems.

Understanding the connection

The plugin connects to the web app using:

• Site key — Authentication credential stored in plugin settings
• Webhook URL — Endpoint for site health monitoring
• REST API — Endpoint for data synchronization
• CORS allowlist — Permitted origins for cross-origin requests

Checking connection status

Status page

1. Go to SEOvault AI > Status
2. Check the Connection Status section
3. Look for:
   • Connection status (Connected / Not Connected)
   • Last connection timestamp
   • Site key status

Connection verification

The plugin tracks connection verification status:

• Verified — Site key successfully authenticated with web app
• Not verified — Connection not yet established or failed

Common connection issues

Invalid or missing site key

Symptoms:

• Status shows “Not Connected”
• API requests return 401 or 403 errors
• Web app cannot access your site data

Causes:

• Site key not configured
• Site key regenerated but not updated in web app
• Site key corrupted during migration

Solutions:

1. Check site key is configured:

   • Go to SEOvault AI > Connection
   • Verify the site key field is not empty

2. Regenerate site key:

   • Go to SEOvault AI > Connection
   • Click Regenerate Site Key
   • Copy the new key
   • Update it in the SEOvault AI web app

3. Verify key in web app:

   • Log in to the SEOvault AI web app
   • Navigate to site settings
   • Ensure the site key matches the plugin

CORS origin not allowlisted

Symptoms:

• Browser console shows CORS errors
• Web app cannot make requests to your site
• Connection fails with network errors

Causes:

• Web app domain not in CORS allowlist
• Site URL changed (HTTP to HTTPS, domain change)
• Allowlist cleared or corrupted

Solutions:

1. Check site URL:

   • Go to Settings > General
   • Verify WordPress Address (URL) and Site Address (URL)
   • Ensure they match the URL registered in the web app

2. Contact support to add your domain to the CORS allowlist if needed

3. Clear browser cache after CORS changes

Rate limiting or lockout

Symptoms:

• API requests return 429 (Too Many Requests)
• Connection works intermittently
• Audit log shows rate limit events

Causes:

• Exceeded API rate limits
• Multiple failed authentication attempts
• IP locked out due to auth failures

Solutions:

1. Check rate limit status:

   • Go to SEOvault AI > Status
   • Review the API Activity Logs section
   • Look for rate limit or lockout events

2. Clear API lockouts:

   • Go to SEOvault AI > Security
   • Click Clear API Lockouts
   • Choose to clear for a specific IP or all IPs

3. Wait for rate limit reset:

   • Rate limits reset automatically after their window expires
   • Auth lockouts expire after 15 minutes

Webhook configuration issues

Symptoms:

• Site health monitoring not working
• No alerts in web app
• Error logs show webhook failures

Causes:

• Webhook URL not configured
• Webhook URL points to wrong endpoint
• HTTPS requirement not met

Solutions:

1. Verify webhook URL:

   • The webhook URL is configured automatically during connection
   • Check that it points to the correct SEOvault backend
   • Must use HTTPS (except localhost for development)

2. Check error logs:

   • Enable WordPress debug logging
   • Check debug.log for webhook errors
   • Look for “Site Health Monitor: Webhook push failed”

SSL/TLS issues

Symptoms:

• HTTPS requests fail
• Certificate errors
• Mixed content warnings

Causes:

• Invalid SSL certificate
• Expired certificate
• Self-signed certificate (production)

Solutions:

1. Check SSL certificate:

   • Use an SSL checker tool
   • Verify certificate is valid and not expired
   • Ensure certificate chain is complete

2. Force HTTPS:

   • Go to Settings > General
   • Set WordPress Address and Site Address to HTTPS
   • Update any hardcoded HTTP URLs

3. Install SSL certificate:

   • Use Let’s Encrypt (free)
   • Contact your hosting provider
   • Ensure SSL is properly configured

Firewall or security plugin blocking

Symptoms:

• Requests blocked with 403 or 404 errors
• Connection works from some locations but not others
• Security plugin logs show blocked requests

Causes:

• Firewall blocking API requests
• Security plugin blocking REST API
• WAF (Web Application Firewall) rules

Solutions:

1. Check firewall rules:

   • Review server firewall configuration
   • Ensure REST API endpoints are not blocked
   • Allow traffic from SEOvault backend IPs

2. Configure security plugin:

   • Add SEOvault REST API namespace to allowlist
   • Exclude /wp-json/seovaultai/v1/ from blocking
   • Check security plugin logs for blocked requests

3. Test with security plugin disabled:

   • Temporarily disable security plugin
   • Test connection
   • If it works, adjust security plugin settings

Testing the connection

Manual API test

Test the API endpoint directly:

curl -X GET https://yoursite.com/wp-json/seovaultai/v1/verify \
  -H "X-Site-Key: your-site-key-here"

Expected response:

{
  "status": "connected",
  "site_key_valid": true
}

Browser console test

1. Open browser developer tools (F12)
2. Go to the Console tab
3. Run:

fetch('https://yoursite.com/wp-json/seovaultai/v1/verify', {
  headers: {
    'X-Site-Key': 'your-site-key-here'
  }
})
.then(r => r.json())
.then(console.log)
.catch(console.error)

WordPress REST API test

1. Go to SEOvault AI > Status
2. Look for REST API availability check
3. If failed, check that WordPress REST API is enabled

Diagnostic information

Gather diagnostic data

When contacting support, provide:

1. Connection status:

   • Status page screenshot
   • Connection timestamp
   • Site key status (configured/empty)

2. Error logs:

   • WordPress debug.log entries
   • Browser console errors
   • Network request failures

3. Site information:

   • WordPress version
   • Plugin version
   • PHP version
   • Site URL (HTTP/HTTPS)

4. Security configuration:

   • Active security plugins
   • Firewall rules
   • WAF configuration

Enable debug logging

Add to wp-config.php:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

Check wp-content/debug.log for errors.

Prevention

Keep credentials secure

• Never share your site key publicly
• Regenerate site key if compromised
• Use read/write keys instead of legacy key when possible

Monitor connection status

• Regularly check the Status page
• Review audit logs for suspicious activity
• Set up alerts for connection failures

Update regularly

• Keep plugin updated to latest version
• Update WordPress core
• Update PHP to supported version

When to contact support

Contact support if:

• Connection fails after following all troubleshooting steps
• You see unexpected error messages
• Connection works intermittently without clear cause
• You need help with CORS allowlist configuration
• You suspect a security issue

Include in your support request:

• Site URL
• Plugin version
• WordPress version
• PHP version
• Status page screenshot
• Relevant error logs
• Steps you’ve already tried

Related docs

• Connector REST API Overview for Developers
• CORS, Rate Limits, and API Activity Logs
• Status Page: Connection, Output Mode, and Site Health Signals