Skip to main content
Start with the operation, error code and returned identifiers. Keep the original request when recovering a write, including its idempotency value when the operation accepts one. The command reference defines each operation’s exact inputs and errors.

​
Authentication or permission failure

401: verify the credential belongs to this API origin. Reconnect OAuth through your MCP client, or replace the API credential through your approved environment setup. 403 AGENT_APPROVAL_REQUIRED: the OAuth token is valid and the client needs human app approval. Preserve the existing token/session. Open the returned approvalUrl and use the returned clientId to review the client in Agent access. Approve its intended workspace, project access and scopes, then retry the read. Opening the link alone does not approve access; reconnecting does not create the grant. 400 WORKSPACE_REQUIRED: select one of the client’s already approved workspaces with X-Workspace-ID. Workspace selection chooses an existing grant. Other 403 errors: check project grants, membership role and every required scope. A valid credential can still lack permission. Ask the workspace administrator for the needed access; retrying the same forbidden call will not widen a grant. Workspace-wide event reads refuse project-limited grants. Operator-only command missing: the admission, library, rank and licensed toolsets and the discover_backlinks command are hidden from ordinary authenticated catalogs and direct calls return TOOL_NOT_FOUND. Documentation and bundled snapshots can contain these commands. Additional scopes or repeated requests do not give a customer operator identity. No command endpoint: your connected release may predate generic commands. Use a documented resource route or registered MCP operation and check availability.

​
Queued, failed or unknown checks

Read the saved job identifier before submitting more work. A pending job can be waiting for admission or execution. Review usage reservations and error details. For an operation with an idempotency contract, replay a lost request with the same payload and value; changing the payload can cause a conflict. For other writes, inspect the operation and saved record before deciding whether to retry. A terminal job with unknown evidence does not prove absence. Read the reason and attempt time. Check a challenge, robots refusal, rate limit or unreadable page through the appropriate browser or publisher route. Do not turn repeated inconclusive attempts into confirmed loss. Evidence states explains the confirmation rule. For BATCH_VERIFICATION_UNAVAILABLE, the server needs its batch migration and release. Use available single-candidate verification when appropriate; do not repeat batch admission indefinitely.

​
Expired history or raw evidence

For CURSOR_EXPIRED, follow the returned snapshot recovery instructions. Persist the snapshot before resuming from its cursor. Keep source and destination cursors separate. Record any lost history interval instead of reporting no changes. For EVIDENCE_EXPIRED, retain observation metadata and its original date. A new authorized check can supply current evidence; it cannot restore the historical page. Follow sync and export for hosted exports and optional local recovery.

​
Local connection conflicts

Run doctor. Check that AGENTLINKOPS_TOKEN and AGENTLINKOPS_API_KEY do not disagree (the LINKTRAIL_* aliases count as the same variables), and that the environment origin matches saved configuration. A .linktrail/ hint means the ledger directory still has its old name; agentlinkops migrate renames it. A ledger connected to another project needs a separate ledger for the new identity. Review the CLI setup before changing files. For local context path refusal, place the handoff inside the configured repository and inspect symlinks. Missing Search Console rows remain missing observations; use manual context when no Google grant exists.

​
Provider refusal

A registered discovery operation can still have disabled admission. Use an export you already hold, or a supplier-backed lookup that your workspace offers. The owned discovery corpus is stopped. Preserve the refusal and mark coverage unavailable. Use the error-code reference for status-specific handling, common schemas for response shapes, and the documentation changelog when a newly documented route is absent from your server.