Most issues fall into a handful of categories — rate limits, API key problems, network reachability, and language drift. This page walks through what each error message means, what’s happening behind it, and the fastest path back to a working state.
“Too many requests. Please try again later.”
You’ve hit one of the plugin’s two built-in rate limits: 100 AI optimizations or 500 filename renames, each per WordPress user per hour. Both buckets are keyed to the user, not to the site, so a second editor has their own allowance.
REST calls draw on the same 100/hour optimization bucket and come back as HTTP 429 with the code infyp_rest_rate_limited. All of one user’s application passwords share that single bucket, so splitting a script across several passwords changes nothing.
Recovery paths
| Feature | What to do |
|---|---|
| Wait the cooldown The 1-hour window rolls forward. | Wait until the hour rolls over, then retry. The window is rolling — if you optimized 100 images between 14:23 and 14:47, you can run again starting at 15:23. |
| Filter and target Optimize only what matters. | Instead of bulk-optimizing everything, filter the image table to the rows you actually need (low score, recent uploads, specific post type) and run just those. Bigger libraries can be paced across multiple hourly windows. |
| Pace a Pro job, don't outrun it Jobs record failures, they don’t wait. | Pro’s server-side jobs work through a library in cron ticks of 20 seconds every 30 seconds, but they do not wait out a rate limit: an image that hits the cap is recorded as a failed item and the job moves on. Split large libraries across runs. See Bulk Optimization (Pro). |
| Raise the cap in code Both buckets are filterable. | The limits and their windows come from a filterable array, so a site that genuinely needs a higher ceiling can raise it in a small plugin rather than working around it. The trade-off is that you also raise the ceiling on a runaway loop. See the filters reference. |
Why this exists
Without the cap, a runaway loop or a bad script could fire thousands of AI calls in a few minutes and spend real money before you noticed. The cap bounds a mistake at 100 calls per user per hour. What those calls actually cost depends on tokens, not images — the API Usage page shows the running estimate, calculated from blended per-token pricing.
API key failures
Start with the Test Key button on the provider’s card on the API Keys page. It sends a zero-token, authenticated models-list request to the provider and reports one of three outcomes, so you learn whether the key or the network is the problem before you touch an image.
What Test Key tells you
| Feature | What it means |
|---|---|
| Valid The provider accepted the key. | The provider answered with a 2xx and the message reads “Key verified with the provider.” Optimization failures after this point are about quota, model access or the network, not the key itself. |
| Invalid The provider rejected it. | The provider answered 400, 401 or 403, and the message you see is the provider’s own error text passed through unchanged. Read it before acting — “identity verification is required”, for example, means a real key blocked at account level, which no amount of re-pasting fixes. |
| Unverified The check itself failed. | A timeout, a network error or an unexpected status. The key is still saved and can be tested again later — this state is deliberately never presented as invalid. Check outbound access first, then retest. |
Results are cached for 5 minutes
A verdict is held for 5 minutes per provider and key, and 1 minute after a network failure, so repeated clicks do not hammer the provider. If you replace a key and immediately retest, wait out the window or the previous answer comes back.
Other API key symptoms
| Feature | What to do |
|---|---|
| The save itself is rejected Rejected before the provider sees it. | Since 1.0.6 the plugin only rejects values that cannot be a secret at all: empty, shorter than 8 characters, longer than 512, or containing spaces or control characters. A rejected save is almost always a partial paste or a line break picked up from the clipboard. Re-copy the whole key and try again. |
| You suspect the wrong provider's key Prefixes are a hint, not a check. |
Anthropic keys usually start with sk-ant-, Google keys with AIza, and OpenAI keys with sk-. Use that to confirm you pasted into the right card, and nothing more: 1.0.6 removed format validation on save, because providers change their key formats and a shape check rejects valid keys sooner or later. Test Key is the authoritative answer.
|
| Optimization fails with "Insufficient quota" Provider billing, not the plugin. | The key is fine and the provider is refusing to bill it. Add or fix the payment method in the provider dashboard, or pick a model from a different provider you hold a key for — the provider follows the model, there is no separate provider switch. |
“Connection timed out” or network errors
The plugin couldn’t reach the AI provider’s API endpoint. Two common causes:
Network reachability
| Feature | What to do |
|---|---|
| Hosting firewall blocking outbound HTTPS Managed hosts often deny outbound by default. |
Allowlist the relevant provider endpoints. The full list is on System Requirements: api.anthropic.com, generativelanguage.googleapis.com, api.openai.com (port 443). For Pro, also allow infypress.com for license validation.
|
| Provider outage It happens. | Check the provider’s status page (status.anthropic.com, status.cloud.google.com, status.openai.com). If they’re degraded, wait it out — or switch to a different provider temporarily by selecting a model from that provider. |
Under connectors, the call is not the plugin’s
With Connection method set to WordPress AI (Connectors) on WordPress 7.0+, WordPress core makes the provider request. Allowlist whatever your configured connectors talk to rather than the three hosts above, and keep infypress.com if you run Pro. If no connector is configured you get a different error entirely — “No AI connector is configured in WordPress” — and the plugin never falls back to your saved keys silently. See AI Connectors.
AI returns English when I asked for another language
First, check the version. Up to 1.0.5 a fresh install fell back to hardcoded English whenever no language had been saved, while the settings screen showed the site language as the selected one. 1.0.6 fixed that: the effective language is your saved setting, and with nothing saved it is the site locale.
Saving the language once settles it
The value lives in infyp_prompt_settings.language as a locale code, chosen from the 133 locales the dropdown offers. Saving it explicitly removes the fallback from the picture entirely, on any version. Do that before you diagnose anything else — it takes a click and rules out the most common cause.
Two causes remain on 1.0.6 and later. The first is the model. On the cheap tier — Claude 4.5 Haiku, Gemini 3.1 Flash-Lite, Gemini 3.5 Flash-Lite, GPT-4.1 mini — rarely used locales sometimes slip back to English, and output varies between runs even with identical input. Switching to a Pro-tier model (Claude 4.5 Sonnet, Gemini 3.1 Pro, GPT-5 mini) is the available lever. Test it on a handful of images before committing a bulk run.
The second is your own prompt add-on. It is inserted into the prompt as written, under the heading PRIMARY REQUIREMENTS (MUST FOLLOW), and truncated at 500 characters — so an add-on written in English argues against the language setting from the strongest position in the prompt. Write it in the target language, or state the language requirement inside it. See Prompt settings and language.
Filenames stay Latin on purpose
Language drift does not apply to filenames. For a language written in a non-Latin script the prompt asks for phonetic transliteration into Latin characters, not translation, because the result becomes part of a URL. A Russian alt text with a filename like krasivyy-zakat is the intended outcome, not a bug.
Pro features disappeared after a license issue
License troubleshooting
| Feature | What to do |
|---|---|
| License page shows "License Issue" Validation has failed. | After a network-error grace period (7 days), Pro features gate off. Renew or re-activate from Image SEO → License. The Renew link in the notice goes straight to your InfyPress account. |
| Pro features missing after a fresh activation Caches lag. | Cached license status is held for 24 hours. After saving a new key, a hard refresh of any plugin admin page is usually enough. If features still don’t appear, deactivate and reactivate the Pro plugin from Plugins to force a re-check. |
| Moving to a new site Don’t activate twice. | Deactivate the license on the old site first (License page → Deactivate). Then enter the same key on the new site. The license slot is occupied while active on one site. |
An old image URL is 404’ing instead of redirecting
Check the redirect's state
| Feature | What to look for |
|---|---|
| Redirect missing entirely from the list Capture may be disabled. | Open Image SEO → Redirects and search for the old URL. If it isn’t there, redirect capture was off when you renamed the file. Re-rename the file (you can rename it back, then rename it forward again) to create the missing 301. |
| Redirect exists but Status column shows "Disabled" Soft-disabled. | Select the row and run the Enable bulk action. Disabled redirects stay in the list but don’t fire 301s. |
| Redirect exists but Status shows "Expired" Past its expiry date. | Expired redirects no longer serve. Delete the row and recreate by re-renaming, or contact support if you need expiry behavior turned off site-wide. |
| Redirect is Active but the URL still 404s CDN or server cache. | Purge your CDN cache and any full-page cache. The 301 fires on your origin server, but a CDN serving a cached 404 will hide it from end users. |
Image SEO Stats numbers look stale
The dashboard cards (Total Images, Keywords %, Filenames %, etc.) are recalculated on a schedule — roughly hourly — not on every page load. If you’ve just optimized a batch and the cards haven’t caught up, give it up to an hour, or reload after the next scheduled run. There’s no manual Recalculate button in the UI.
The Debug page (when nothing else explains it)
The plugin ships with a Debug page that surfaces system info, recent errors, API health, and a downloadable diagnostic bundle — useful when you’re chasing an obscure issue or when support asks for one.
The Debug page only appears when WP_DEBUG is enabled
By design, the Debug submenu is hidden on production sites. To use it, add define( 'WP_DEBUG', true ); to your wp-config.php (and optionally WP_DEBUG_LOG to capture logs to a file). Refresh WP Admin and the Debug page appears under Image SEO. Disable WP_DEBUG again when you’re done — running it in production is a security hazard.
Where to get help
If your issue isn’t covered here:
Support channels
| Feature | Best for |
|---|---|
| WordPress.org support forum Free plugin. | Public Q&A for the free plugin. Search before posting — most issues have been answered before. |
| InfyPress support Pro license holders. | Direct support for license holders. Include a downloaded Debug Information bundle (from the Debug page) when reporting an issue — it carries the system info needed to reproduce it. |
| Your provider's status page Provider-side issues. | Before opening a ticket, glance at the AI provider’s status page. Many “the plugin broke” tickets turn out to be a brief provider outage. |