AEO Enhancer
Install on Shopify

Common errors

Fix the most common issues in AEO Enhancer, including reconnect, rate limits, and preview mismatch.

Common errors

This page covers the most common errors you may see in AEO Enhancer and how to resolve them.

If you are blocked, start here first.

Auth required or reconnect needed

Symptoms

  • You see an auth required banner
  • API calls fail with unauthorized errors
  • Actions like execute or rollback fail even though the preview loads

Why it happens

The Shopify offline token can expire or be revoked, or the app may not have a valid session for the current embedded context.

Fix

  1. Click Reconnect to Shopify in the banner or task modal
  2. Complete the Shopify OAuth flow
  3. Return to the task and retry the action

If it still fails:

  • Confirm you are in the correct store admin
  • Confirm your user role still has access to the app
  • Try a hard refresh of the embedded app

Rate limited

Symptoms

  • Requests fail with a rate limit message
  • You see a RATE_LIMITED error code with a request id

Why it happens

Rate limits protect your store and the app from burst activity. Limits can apply to:

  • App API routes
  • External services used for generation or retesting
  • Background runners

Fix

  1. Retry the action after a short pause
  2. Reduce repeated clicks on the same action
  3. If this is frequent, review plan limits and usage

If you need support, include the request id shown in the error.

Quota or budget exceeded

Symptoms

  • Content generation fails with budget or quota errors
  • Retests or competitor discovery do not run

Why it happens

Some features have plan based weekly quotas or per request budget caps.

Fix

  1. Check your plan limits and current usage in Settings
  2. Reduce the number of active queries or tasks you are generating in a short period
  3. Upgrade plan if needed for higher usage

Preview missing

Symptoms

  • Task modal opens but there is no preview content
  • Approval buttons are disabled

Why it happens

A task must have a preview before it can be approved. If preview generation fails, the task stays blocked.

Common causes:

  • External service error during generation
  • Validation error on the generated output
  • Budget or quota exceeded

Fix

  1. Retry task creation
  2. Check for an error code in the UI
  3. If the error persists, capture the task id and the error details and contact support

Preview mismatch or integrity check failed

Symptoms

  • Execute fails after approval
  • Error mentions preview mismatch or integrity check

Why it happens

Execution is locked to the approved preview. If the approved version does not match the active preview, execution is blocked.

This protects you from executing content you did not approve.

Fix

  1. Open the task preview versions panel
  2. Confirm which version is approved
  3. Set that version active if needed
  4. If you want a different version, reset approval, then approve the correct version
  5. Retry execute

Shopify resource not found during rollback

Symptoms

  • Rollback fails for a blog draft or other created resource
  • Error indicates a missing resource id

Why it happens

A resource may have been deleted manually in Shopify after execution.

Fix

  1. Do not manually delete draft resources created by the app until you are sure you will not roll back
  2. If it already happened, contact support with the task id
  3. In many cases, the app can still roll back approved metafields even if the draft resource is missing

Task stuck in a state

Symptoms

  • Task shows approved but cannot execute
  • Task shows executing but never completes

Why it happens

Usually one of:

  • Shopify auth expired mid action
  • Rate limit hit during execution
  • External service timeout
  • Network interruption during the action

Fix

  1. Refresh the app
  2. Check timeline for the last event
  3. Retry the action
  4. If it fails, reconnect and retry once more

If it still fails, capture the task id and error details and contact support.

When to contact support

Contact support if:

  • The same error repeats after reconnect and retry
  • You see an unknown error code
  • Rollback cannot complete and you need the store reverted

Include:

  • Store domain
  • Task id
  • Error code and message
  • Screenshot of the task timeline
  • Core concepts then Approval first
  • Core concepts then Tasks
  • Workflows then Preview approve execute rollback
  • Policies then Permissions