seo/wordpress-plugins/rank-math-api-manager/docs/troubleshooting.md

Troubleshooting Guide - Rank Math API Manager Plugin

📋 Overview

This guide helps you identify and resolve common issues with the Rank Math API Manager plugin. Follow the troubleshooting steps to diagnose and fix problems quickly.

🔍 Quick Diagnostic Checklist

Before diving into specific issues, run through this checklist:

• ✅ Plugin is activated in WordPress admin
• ✅ Rank Math SEO plugin is installed and active
• ✅ WordPress REST API is accessible
• ✅ Application Password is correctly configured
• ✅ User has edit_posts permissions
• ✅ Post ID exists and is published
• ✅ HTTPS is enabled (recommended for security)

🚨 Common Error Codes

401 Unauthorized

Error Message: "Sorry, you are not allowed to do that."

Possible Causes:

1. Invalid credentials
2. Missing Application Password
3. Incorrect username
4. User lacks permissions

Solutions:

Step 1: Verify Application Password

# Test with cURL
curl -X POST "https://your-site.com/wp-json/rank-math-api/v1/update-meta" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic [your-base64-credentials]" \
  -d "post_id=123&rank_math_title=Test"

Step 2: Check User Permissions

1. Go to Users → All Users
2. Find your user account
3. Verify role has edit_posts capability
4. Check if user is active

Step 3: Regenerate Application Password

1. Go to Users → Profile
2. Scroll to "Application Passwords"
3. Delete existing password
4. Create new Application Password
5. Update your integration

Step 4: Verify Base64 Encoding

# Test encoding
echo -n "username:application_password" | base64

404 Not Found

Error Message: "No route was found matching the URL and request method"

Possible Causes:

1. Plugin not activated
2. WordPress REST API disabled
3. Incorrect endpoint URL
4. Permalink structure issues

Solutions:

Step 1: Check Plugin Status

1. Go to Plugins → Installed Plugins
2. Verify "Rank Math API Manager" is Active
3. Check for any error messages

Step 2: Test REST API

# Test WordPress REST API
curl -X GET "https://your-site.com/wp-json/wp/v2/posts"

Step 3: Check Permalinks

1. Go to Settings → Permalinks
2. Select any option other than "Plain"
3. Save changes

Step 4: Verify Endpoint URL

# Test endpoint availability
curl -X GET "https://your-site.com/wp-json/rank-math-api/v1/update-meta"

Expected response: 404 (confirms endpoint exists but requires POST)

400 Bad Request

Error Message: "No metadata was updated"

Possible Causes:

1. Missing post_id
2. Invalid post ID
3. No SEO fields provided
4. Invalid data format

Solutions:

Step 1: Verify Post ID

# Check if post exists
curl -X GET "https://your-site.com/wp-json/wp/v2/posts/123"

Step 2: Check Request Format

# Ensure proper form data
curl -X POST "https://your-site.com/wp-json/rank-math-api/v1/update-meta" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic [credentials]" \
  -d "post_id=123&rank_math_title=Test Title"

Step 3: Verify Post Status

1. Go to Posts → All Posts
2. Find the post by ID
3. Ensure status is "Published"

500 Internal Server Error

Error Message: Various server error messages

Possible Causes:

1. PHP memory limit exceeded
2. Plugin conflicts
3. Server configuration issues
4. Database connection problems

Solutions:

Step 1: Enable Debug Mode

// Add to wp-config.php
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);

Step 2: Check Error Logs

# Check WordPress debug log
tail -f wp-content/debug.log

# Check server error logs
tail -f /var/log/apache2/error.log
# or
tail -f /var/log/nginx/error.log

Step 3: Increase Memory Limit

// Add to wp-config.php
define('WP_MEMORY_LIMIT', '256M');

Step 4: Test Plugin Conflicts

1. Deactivate all plugins except Rank Math SEO and Rank Math API Manager
2. Test the API endpoint
3. Reactivate plugins one by one to identify conflicts

🔧 Integration-Specific Issues

n8n Integration Problems

Issue: Authentication Fails in n8n

Symptoms: 401 errors in n8n workflow

Solutions:

1. Check Credential Configuration

   • Verify username and Application Password
   • Ensure no extra spaces or characters
   • Test credentials manually first

2. Update n8n Node Configuration

{
  "authentication": "httpBasicAuth",
  "username": "your_username",
  "password": "your_application_password"
}

3. Test with Simple Request

{
  "method": "POST",
  "url": "https://your-site.com/wp-json/rank-math-api/v1/update-meta",
  "contentType": "form-urlencoded",
  "bodyParameters": {
    "post_id": "123",
    "rank_math_title": "Test Title"
  }
}

Issue: Data Mapping Errors

Symptoms: Missing or incorrect data in API calls

Solutions:

1. Add Data Validation Node

// Add Code node before HTTP Request
const postId = $("Previous Node").first().json.post_id;
const seoTitle = $("Previous Node").first().json.seo_title;

if (!postId || !seoTitle) {
  throw new Error("Missing required data");
}

return {
  post_id: postId,
  rank_math_title: seoTitle,
  rank_math_description: $("Previous Node").first().json.seo_description || "",
  rank_math_focus_keyword: $("Previous Node").first().json.focus_keyword || "",
};

2. Add Error Handling

// Add Code node after HTTP Request
const response = $("HTTP Request").first().json;

if (response.error) {
  throw new Error(`API Error: ${response.error}`);
}

return {
  success: true,
  data: response,
};

Zapier Integration Problems

Issue: Code Action Fails

Symptoms: JavaScript errors in Zapier

Solutions:

1. Add Error Handling

try {
  const response = await fetch(
    "https://your-site.com/wp-json/rank-math-api/v1/update-meta",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/x-www-form-urlencoded",
        Authorization: "Basic " + btoa("username:application_password"),
      },
      body: new URLSearchParams({
        post_id: inputData.post_id,
        rank_math_title: inputData.seo_title,
        rank_math_description: inputData.seo_description,
        rank_math_focus_keyword: inputData.focus_keyword,
      }),
    }
  );

  const result = await response.json();

  if (!response.ok) {
    throw new Error(
      `HTTP ${response.status}: ${result.message || "Unknown error"}`
    );
  }

  return { success: true, data: result };
} catch (error) {
  return { success: false, error: error.message };
}

2. Validate Input Data

// Validate required fields
if (!inputData.post_id) {
  throw new Error("Post ID is required");
}

if (!inputData.seo_title) {
  throw new Error("SEO title is required");
}

Python Integration Problems

Issue: SSL Certificate Errors

Symptoms: SSL verification failures

Solutions:

import requests
import urllib3

# Disable SSL warnings (not recommended for production)
urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)

# Make request with SSL verification disabled
response = requests.post(url, headers=headers, data=data, verify=False)

Issue: Connection Timeouts

Symptoms: Request timeouts

Solutions:

import requests

# Set timeout
response = requests.post(url, headers=headers, data=data, timeout=30)

# Retry logic
from requests.adapters import HTTPAdapter
from requests.packages.urllib3.util.retry import Retry

session = requests.Session()
retry = Retry(connect=3, backoff_factor=0.5)
adapter = HTTPAdapter(max_retries=retry)
session.mount('http://', adapter)
session.mount('https://', adapter)

response = session.post(url, headers=headers, data=data)

🛠️ Advanced Troubleshooting

Debug Mode Setup

Step 1: Enable WordPress Debug

// Add to wp-config.php
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);
define('WP_DEBUG_DISPLAY', false);
define('SCRIPT_DEBUG', true);

Step 2: Add Plugin Debug Logging

// Add to your theme's functions.php or a custom plugin
add_action('rest_api_init', function() {
    error_log('REST API initialized');
});

add_action('wp_rest_server_class', function($class) {
    error_log('REST server class: ' . $class);
});

Step 3: Monitor API Requests

// Add to your theme's functions.php
add_action('rest_api_init', function() {
    add_filter('rest_pre_dispatch', function($result, $server, $request) {
        error_log('API Request: ' . $request->get_route());
        error_log('API Method: ' . $request->get_method());
        error_log('API Params: ' . json_encode($request->get_params()));
        return $result;
    }, 10, 3);
});

Performance Issues

Issue: Slow API Responses

Solutions:

1. Optimize Database Queries

// Add to wp-config.php
define('SAVEQUERIES', true);

2. Check Server Resources

# Monitor server resources
htop
free -h
df -h

3. Enable Caching

// Add caching headers
add_action('rest_api_init', function() {
    add_filter('rest_post_dispatch', function($response, $handler, $request) {
        $response->header('Cache-Control', 'public, max-age=300');
        return $response;
    }, 10, 3);
});

Security Issues

Issue: Unauthorized Access Attempts

Solutions:

1. Implement Rate Limiting

// Add rate limiting
add_action('rest_api_init', function() {
    add_filter('rest_pre_dispatch', function($result, $server, $request) {
        $ip = $_SERVER['REMOTE_ADDR'];
        $key = 'api_rate_limit_' . $ip;
        $count = get_transient($key);

        if ($count && $count > 100) {
            return new WP_Error('rate_limit_exceeded', 'Rate limit exceeded', ['status' => 429]);
        }

        set_transient($key, ($count ? $count + 1 : 1), 3600);
        return $result;
    }, 10, 3);
});

2. Log Security Events

// Log failed authentication attempts
add_action('rest_authentication_errors', function($result) {
    if ($result !== null) {
        error_log('Failed API authentication attempt from IP: ' . $_SERVER['REMOTE_ADDR']);
    }
    return $result;
});

📊 Monitoring and Logging

Set Up Monitoring

Step 1: Create Health Check Endpoint

// Add to your plugin
add_action('rest_api_init', function() {
    register_rest_route('rank-math-api/v1', '/health', [
        'methods' => 'GET',
        'callback' => function() {
            return [
                'status' => 'healthy',
                'timestamp' => current_time('mysql'),
                'version' => '1.0.6'
            ];
        },
        'permission_callback' => '__return_true'
    ]);
});

Step 2: Monitor API Usage

// Track API usage
add_action('rest_api_init', function() {
    add_filter('rest_post_dispatch', function($response, $handler, $request) {
        if (strpos($request->get_route(), 'rank-math-api') !== false) {
            $usage = get_option('rank_math_api_usage', []);
            $date = date('Y-m-d');
            $usage[$date] = ($usage[$date] ?? 0) + 1;
            update_option('rank_math_api_usage', $usage);
        }
        return $response;
    }, 10, 3);
});

Log Analysis

Step 1: Parse WordPress Debug Log

# Find API-related errors
grep "rank-math-api" wp-content/debug.log

# Find authentication errors
grep "authentication" wp-content/debug.log

# Find recent errors
tail -n 100 wp-content/debug.log | grep "ERROR"

Step 2: Monitor Server Logs

# Apache error logs
tail -f /var/log/apache2/error.log | grep "your-domain.com"

# Nginx error logs
tail -f /var/log/nginx/error.log | grep "your-domain.com"

🆘 Getting Help

Before Contacting Support

1. Collect Information:

   • WordPress version
   • Plugin version
   • PHP version
   • Server environment
   • Complete error messages
   • Request/response data

2. Test with Minimal Setup:

   • Deactivate other plugins
   • Switch to default theme
   • Test with basic cURL request

3. Check Known Issues:

   • Review GitHub issues
   • Check documentation
   • Search community forums

Contact Information

• GitHub Issues: Create an issue
• Email Support: devora.no
• Documentation: docs/

Required Information for Support

When contacting support, include:

WordPress Version: X.X.X
Plugin Version: X.X.X
PHP Version: X.X.X
Server: Apache/Nginx
Error Message: [Complete error message]
Request Data: [API request details]
Response Data: [API response details]
Steps to Reproduce: [Detailed steps]
Environment: [Local/Staging/Production]

---

Related Documentation:

• Installation Guide
• API Documentation
• Integration Guide

---

Last Updated: July 2025
Version: 1.0.6