Integration Errors

Platform-specific error codes and solutions for WordPress, Ghost, Tilda, Wix, Payload CMS, and Webhook integrations. Find detailed troubleshooting steps for each integration type.

🔌 WordPress Integration Errors

Error: rest_cannot_create (403 Forbidden)

Full Error:

{
  "code": "rest_cannot_create",
  "message": "Sorry, you are not allowed to create posts as this user.",
  "data": { "status": 403 }
}

Cause:

• Application Password doesn't have sufficient permissions
• User account is not an Administrator or Editor

Solutions:

Error: rest_post_invalid_page_number (400 Bad Request)

Full Error:

{
  "code": "rest_post_invalid_page_number",
  "message": "The page number requested is larger than the number of pages available.",
  "data": { "status": 400 }
}

Cause:

• Forest SEO attempting to fetch non-existent pagination page
• Usually occurs during initial sync

Solution: This is typically a temporary error during sync. Wait 5-10 minutes and the integration should complete automatically. If persists:

1. Go to Integrations → WordPress
2. Click "Re-sync"
3. Wait for sync to complete

Error: rest_cookie_invalid_nonce (403 Forbidden)

Full Error:

{
  "code": "rest_cookie_invalid_nonce",
  "message": "Cookie check failed",
  "data": { "status": 403 }
}

Cause:

• Not applicable to Application Password authentication
• Indicates Forest SEO is incorrectly using cookie authentication

Solution: This shouldn't happen with proper Application Password setup. If you see this:

1. Delete the integration
2. Recreate with fresh Application Password
3. Ensure you're using Application Password, not regular password
4. If still occurs, contact [email protected]

Error: rest_no_route (404 Not Found)

Full Error:

{
  "code": "rest_no_route",
  "message": "No route was found matching the URL and request method",
  "data": { "status": 404 }
}

Cause:

• WordPress REST API disabled
• Incorrect site URL
• Permalinks set to "Plain"

Solutions:

1. Check Site URL

❌ Wrong:
https://yoursite.com/wp-admin
https://yoursite.com/wordpress
http://yoursite.com (HTTPS site with HTTP URL)

✅ Correct:
https://yoursite.com

2. Check Permalinks

WordPress Admin → Settings → Permalinks
Must NOT be set to "Plain"

✓ Post name
✓ Day and name
✓ Month and name
✓ Numeric
✓ Custom structure

If set to Plain:

1. Choose any other option (recommend "Post name")
2. Click Save Changes
3. Test Forest SEO connection again

3. Verify REST API Enabled

Visit in browser (replace your-site.com):

https://your-site.com/wp-json/wp/v2/posts

Expected: JSON response with posts array
Error 404: REST API is disabled or blocked

Enable REST API:

• Check for "Disable REST API" plugin → Uninstall
• Check .htaccess for REST API blocks
• Contact hosting provider if REST API blocked at server level

Error: Connection timeout

Symptoms:

• "Connection timed out" error
• Integration test hangs for 30+ seconds
• No response from WordPress site

Causes & Solutions:

1. Server Response Too Slow

Hosting issues:

• Shared hosting overloaded
• WordPress site has performance issues
• Too many plugins slowing response

Solutions:

• Optimize WordPress (caching plugin, image optimization)
• Upgrade hosting plan
• Contact hosting support

2. Firewall Blocking Forest SEO

Check with hosting provider:

• Provide Forest SEO IP addresses (contact support for list)
• Ask to whitelist in server firewall
• Or temporarily disable firewall, test, re-enable

3. CloudFlare or CDN Issues

If using Cloudflare:

1. Cloudflare Dashboard → Security → WAF
2. Create firewall rule to allow Forest SEO IPs
3. Or set Security Level to "Medium"

👻 Ghost Integration Errors

Error: UnauthorizedError: Authorization failed

Full Error:

{
  "errors": [{
    "message": "Authorization failed",
    "type": "UnauthorizedError"
  }]
}

Cause:

• Invalid Admin API Key
• API Key doesn't match Ghost version
• Key expired or revoked

Solutions:

❌ Wrong:
https://yourblog.ghost.io/ghost/api
https://yourblog.ghost.io/admin

✅ Correct:
https://yourblog.ghost.io

Ghost Admin → Settings → About

Error: ValidationError: Resource not found

Full Error:

{
  "errors": [{
    "message": "Resource not found",
    "type": "ValidationError"
  }]
}

Cause:

• Incorrect site URL
• Staff user not found
• Tag or category doesn't exist

Solutions:

1. Verify Site URL

For Ghost(Pro):

Format: https://yoursite.ghost.io

For Self-Hosted Ghost:

Format: https://yourblog.com

2. Check Staff User

API Key must belong to active staff user:

1. Ghost Admin → Settings → Staff
2. Verify user who created API key is active
3. If suspended, reactivate or create new integration

Error: NoPermissionError: You do not have permission

Cause:

• Staff user role is "Contributor" (needs Author, Editor, or Administrator)
• Ghost permissions changed after API key creation

Solution:

Update User Role:

1. Ghost Admin → Settings → Staff
2. Find user who created API key
3. Change role to Author or higher
4. Test integration again

🎨 Tilda Integration Errors

Error: Invalid API Key

Symptoms:

• "Authentication failed" during connection test
• "Invalid or expired API key" message

Solutions:

Error: Rate limit exceeded

Symptoms:

• "Too many requests" error
• Publishing paused temporarily

Cause:

• Tilda API has rate limits (typically 120 requests/minute)

Solution:

• Wait 60 seconds
• Retry publishing
• If publishing multiple articles, use schedules to spread load
• Contact Tilda support for rate limit increase

🔧 Wix Integration Errors

Error: Authentication failed - Invalid OAuth token

Cause:

• OAuth token expired (tokens expire after 90 days)
• Integration disconnected

Solution:

Reconnect Integration:

1. Go to Integrations → Wix
2. Click "Reconnect"
3. Sign in to Wix when prompted
4. Grant permissions
5. Test connection

Error: Site not found

Cause:

• Incorrect Site ID
• Site was deleted or suspended
• No access to selected site

Solutions:

1. Verify Site ID

Find Site ID:

1. Wix Dashboard → Site selector
2. Select your site
3. URL shows: wix.com/dashboard/SITE_ID_HERE
4. Copy Site ID
5. Update in Forest SEO

2. Check Site Access

Ensure your Wix account has:

• Owner or Admin role on the site
• Site is published (not in draft)
• Site has active subscription if required

📦 Payload CMS Integration Errors

Error: Unauthorized - Authentication required

Cause:

• Invalid API credentials
• User doesn't have collection access
• API endpoint security misconfigured

Solutions:

Format: https://your-api.com/api
(Include /api path)

Header: Authorization: JWT YOUR_TOKEN

Header: X-API-Key: YOUR_API_KEY

🌐 Webhook Integration Errors

Error: Connection refused or ECONNREFUSED

Symptoms:

• Webhook fails to connect to endpoint
• "Connection refused" in error log
• No response from webhook URL

Causes & Solutions:

1. Webhook URL Unreachable

Check URL:

❌ Wrong:
http://localhost:3000/webhook (localhost not accessible)
https://192.168.1.100/api (private IP)

✅ Correct:
https://yourapp.com/api/webhook (public URL)
https://api.yourservice.com/hook

Test webhook endpoint:

curl -X POST https://your-webhook-url.com/hook \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

Should return 200 OK or 202 Accepted.

2. Firewall or Network Issues

Solutions:

• Ensure webhook server accepts incoming connections
• Check firewall allows HTTPS (port 443)
• Whitelist Forest SEO IPs (contact support for list)

Error: SSL certificate verification failed

Full Error:

unable to verify the first certificate

Cause:

• Self-signed SSL certificate
• Expired SSL certificate
• Incomplete certificate chain

Solutions:

1. Use Valid SSL Certificate

Options:

• Get free certificate from Let's Encrypt
• Purchase certificate from trusted CA
• Use cloud provider's certificate (Cloudflare, AWS Certificate Manager)

2. Verify Certificate Chain

Test SSL configuration:

curl -v https://your-webhook-url.com/hook

Look for "SSL certificate verify ok" in output.

Fix Certificate Chain:

• Include intermediate certificates
• Ensure root CA certificate installed

Error: Webhook returned error: 401 Unauthorized

Cause:

• Missing authentication headers
• Invalid API key/token
• Authentication header format incorrect

Solutions:

{
  "Authorization": "Bearer YOUR_TOKEN",
  "X-API-Key": "your-api-key"
}

Error: Webhook timeout - no response after 30 seconds

Cause:

• Webhook endpoint processing too slowly
• Server overloaded
• Long-running operations blocking response

Solutions:

1. Optimize Webhook Handler

Best Practice:

// ❌ Slow - processes before responding
app.post('/webhook', async (req, res) => {
  await processArticle(req.body); // Takes 45 seconds
  res.status(200).send('OK');
});

// ✅ Fast - respond immediately, process async
app.post('/webhook', async (req, res) => {
  res.status(202).send('Accepted'); // Respond first
  
  // Process in background
  processArticle(req.body).catch(err => console.error(err));
});

Requirements:

• Respond within 30 seconds
• Return 200-299 status code
• Process data asynchronously if needed

2. Increase Server Resources

If webhook server is overloaded:

• Scale up server (more CPU/RAM)
• Optimize code and database queries
• Use queue system for heavy processing

Error: Webhook returned error: 500 Internal Server Error

Cause:

• Error in webhook handler code
• Database connection failed
• Unexpected data format

Solutions:

# Common log locations
/var/log/nginx/error.log
/var/log/apache2/error.log
pm2 logs (for Node.js)

{
  "event": "content.published",
  "data": {
    "id": "content_abc123",
    "title": "Article Title",
    "content": "...",
    "meta_description": "...",
    "language": "en",
    "published_at": "2024-01-15T10:00:00Z"
  }
}

app.post('/webhook', async (req, res) => {
  try {
    // Validate payload
    if (!req.body || !req.body.data) {
      return res.status(400).json({ 
        error: 'Invalid payload' 
      });
    }
    
    // Process
    await handleContent(req.body.data);
    
    // Success
    res.status(200).json({ 
      success: true 
    });
    
  } catch (error) {
    console.error('Webhook error:', error);
    
    // Return error to Forest SEO
    res.status(500).json({ 
      error: error.message 
    });
  }
});

🔄 General Integration Tips

Testing Integrations

Before publishing to production:

Test Checklist:

• Connection test passes
• Test article publishes successfully
• Article appears on website
• Article has correct formatting
• Images load correctly
• Meta tags populated
• No duplicate posts created

Integration Logs

Check integration logs for detailed errors:

Access Logs:

1. Go to Integrations → [Your Integration]
2. Click "View Logs" or "History"
3. Review recent operations
4. Note error codes and timestamps
5. Send to support if need help

Re-authentication

Many integrations require periodic re-authentication:

Signs re-auth needed:

• "Token expired" errors
• "Authentication failed" suddenly
• 401 Unauthorized errors

Solution:

• Click "Reconnect" in integration settings
• Re-authorize when prompted

📚 Related Documentation

🆘 Still Stuck?