Troubleshooting & Common Issues

1. API connection errors

If the Test API Connection button returns an error, check:

• The correct provider is selected (OpenAI vs OpenRouter).
• Your API key is valid, active and not expired.
• The key matches the provider (OpenAI keys do not work on OpenRouter, and vice versa).
• There is no extra space before or after the key.

The error message usually comes directly from the provider (e.g. 401 – invalid API key). Fix the underlying issue, save your settings and test again.

2. HTTP 429 – quota exceeded

A 429 status code means the AI provider is rate-limiting you:

• Too many requests in a short time (per account or per IP).
• Free tier exhausted (OpenRouter “free” models, OpenAI trial, etc.).
• Account-specific limits reached on the provider dashboard.

In this situation, AI Auto-SEO Writer:

• Does not overwrite your existing metas.
• Displays a message explaining the quota problem.
• Recommends waiting a few minutes or switching model/provider.

Check your provider dashboard (OpenAI / OpenRouter) for usage and limits, then try again later.

3. Timeout & slow responses

If generation appears to hang or the popup never shows, you may be facing timeouts:

• Server response too slow (shared hosting under load).
• Very long content being sent to the AI model.
• Temporary network issues between your server and the AI provider.

Recommended actions:

• Try again with shorter content (for testing).
• Check your PHP max_execution_time and memory limits.
• Temporarily disable heavy plugins that may slow admin-ajax requests.

4. Cache & security plugin conflicts

Some cache, firewall or security plugins can interfere with the plugin’s REST API calls:

• Blocking /wp-json/ routes in the admin.
• Minifying or combining scripts in a way that breaks the JavaScript.
• Adding aggressive HTTP security headers that prevent requests.

To test for conflicts:

• Temporarily disable cache / security plugins.
• Clear all caches (including server-level and CDN, if any).
• Reload the post editor and try generating SEO again.

5. Models list not loading

If the model select remains empty or shows an error:

• Ensure you have saved a valid API key for the selected provider.
• Verify that your role has the capability manage_options.
• Check that the AI provider setting matches your key (OpenAI vs OpenRouter).
• Open your browser console (Network tab) and look for failed requests to /wpaiso/v1/get-models.

Error codes like 401 or 429 come from the provider and usually indicate an authentication or quota issue.

6. Debugging with browser developer tools

For advanced troubleshooting, we recommend using your browser DevTools:

• Open the Console tab to see JavaScript warnings or error messages.
• Open the Network tab and filter by wpaiso or wp-json.
• Click on the /wpaiso/v1/generate and /wpaiso/v1/optimize-content entries.
• Inspect the Response panel to read the exact error returned by the server.

When contacting support, including screenshots from Console and Network tabs greatly speeds up diagnosis.