Troubleshooting — Error → Cause → Fix

Authentication Errors

invalid_bearer_token (401)

Cause: The token has expired, was revoked, or does not exist. Fix:

1. Open the My Tokens page on your platform.
2. If the token is marked Revoked → generate a new one.
3. If marked Active but still failing → make sure you copied it in full, including the prefix.

token_expired (401)

Cause: The access token exceeded its validity window. Fix: Most agents refresh automatically. If not, reconnect the site to the agent, or generate a new prompt from the My Tokens page.

refresh_token_expired (400)

Cause: The refresh token exceeded its validity window. Fix: Reconnect the site to the agent — a full OAuth PKCE flow issues a fresh token pair.

invalid_client (401)

Cause: The AI client is not a recognised OAuth client. Fix: Verify the client identifier your agent sends matches a client the plugin accepts.

pkce_verification_failed (400)

Cause: The code_verifier does not match the code_challenge. Fix: Usually a client-side issue — update the AI client to its latest version and retry the connection.

Routing Errors

Manifest not found (404)

Cause: The site’s URL rewriting / clean URLs are not enabled, so the manifest route isn’t reachable. Fix: Enable clean/pretty URLs on your platform and clear its cache, then try the manifest URL again. See the plugin’s installation guide for the exact setting.

Route not registered

Cause: The plugin’s routes weren’t rebuilt after an install or update. Fix: Re-run the platform’s cache/route rebuild (or deactivate + reactivate the plugin), then retry.

Tool Execution Errors

Tool not found

Cause: The site isn’t connected in the agent, or the tool name doesn’t match what the manifest exposes. Fix:

1. Verify the site is connected in your agent (re-add it if missing).
2. Call the tool by the exact name shown in the manifest / connection prompt.

insufficient_scope (403)

Cause: Calling a write/admin tool with a token that only has read scope. Fix: Reconnect with the required scope, or upgrade to the Pro edition that includes the tool.

Permission denied

Cause: The user who created the token doesn’t have the underlying platform permission for that action. Scope is the ceiling — the user’s own permissions are the floor. Fix: Grant the user the appropriate role/permission on the platform, then retry.

Not found (for a specific resource)

Cause: The ID doesn’t exist, or belongs to a different context (for example, a different store in a multi-store setup). Fix: Verify the ID matches what you see in the admin panel, and that you’re targeting the right site.

Rate Limit Errors

rate_limit_exceeded (429)

Cause: Too many requests in a short window. Fix:

1. Wait the number of seconds shown in retry_after.
2. Add a small delay between the agent’s requests.
3. Adjust the limit in the plugin’s settings if you legitimately need more throughput.

Network Errors

502 Bad Gateway / service not responding

Cause: For plugins that run a separate backend service, that service isn’t running. Fix: Restart the plugin’s backend service and confirm it’s up, then retry.

CORS blocked (browser only)

Cause: The reverse proxy isn’t sending CORS headers. Fix: Add the appropriate Access-Control-Allow-* headers for your agent’s origin in your web server / reverse proxy config.

SSL verification failed

Cause: The SSL certificate is invalid or self-signed. Fix: Install a valid certificate (a free option such as Let’s Encrypt is sufficient).

Getting More Help

If you couldn’t resolve the issue:

1. Note the details — platform, plugin version, the exact error, the tool name, and the AI client.
2. Contact support.

Security Vulnerability Reports

• Do not post publicly — this may expose users before a fix is available.
• Contact us.
• Include: platform, reproduction steps, and expected impact.