Fix

Fix it from the symptom

8 symptoms, each with cause and fix. Codes link to the stable table.

Updated 2026-11-08

On this page

Fix · troubleshooting

8 symptoms, each with cause and fix. Error codes link to the stable table.

  • 401 AUTH_UNAUTHORIZED on every call

    Cause: Missing, revoked, or expired key — or the key lacks the scope. Both look identical on purpose.

    Fix: Re-issue or re-copy the raw key, confirm it is sent as Authorization: Bearer, and confirm the endpoint's scope is covered. See the scope matrix.

  • 403 SITE_NOT_VERIFIED when triggering an audit

    Cause: The site is registered under your key but ownership was never verified.

    Fix: Run the verify step first, then retry the audit. See the ownership guide.

  • 429 with Retry-After (quota or rate limit)

    Cause: Key monthly read quota, audit frequency/URL quotas, or 100 req/min per IP.

    Fix: Honor Retry-After, check remaining via GET /v1/ai/quota, and upgrade or wait for the window (720h rolling for key reads).

  • Webhook signature mismatch

    Cause: Wrong secret, or the body was re-serialized before verifying.

    Fix: Verify the raw bytes, not the parsed object: v1 = HMAC-SHA256(secret, `${t}.${event}.${rawBody}`), where t comes from X-Seo-Watch-Signature (t=...,v1=...), event from X-Seo-Watch-Event, and rawBody is the unparsed body. Also reject deliveries whose timestamp is more than 300 seconds off — a stale signature is a mismatch even when the HMAC is correct.

  • MCP tools/call answers 401 -32002

    Cause: The credential reaching the tool doesn't cover it: an OAuth access token past its 1h lifetime with a dead refresh, or an API key whose scopes miss the tool's requirement. Write tools also reject read-only credentials.

    Fix: Reconnect the client from the /mcp page (fresh consent reissues tokens), or issue a key with the tool's scope. tools/list shows the required scope per tool.

  • Search Console views are empty

    Cause: No property is bound, the bound property lost its permission, or the Google grant was revoked on the account's security page.

    Fix: In the console, reconnect with Google and rebind the property — the property list comes straight from your account, so anything you can see there can bind.

  • Share link creation answers 403 SiteQuotaExceeded

    Cause: The link requested unbranded rendering without a commercial license. White-label views require 5+ sites; branded links are never gated.

    Fix: Create the link without the unbranded toggle, or add sites to reach 5 — the error carries an upgrade pointer.

  • OpenCode drops my static Authorization header

    Cause: The client discards configured headers when a server advertises OAuth discovery — our MCP endpoint does. Configuring both auth modes is the conflict.

    Fix: Pick one: remove the header and let OpenCode run the browser sign-in, or keep the header on a client that doesn't force OAuth.