> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentlinkops.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Recover failed connections and interrupted work

> Resolve authentication and scope errors, pending or unknown checks, expired evidence and cursors, local sync conflicts and webhook failures.

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](/reference/index) 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](/guides/connect-mcp), or replace the API credential through your approved environment setup.

**403:** check workspace selection, 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.

**No command endpoint:** your connected release may predate generic commands. Use a documented resource route or registered MCP operation and check [availability](/capability-status).

## 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](/evidence) 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](/guides/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](/guides/connect-cli) 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](/guides/local-context) when no Google grant exists.

## Provider or delivery refusal

A registered discovery operation can still have disabled admission. Use a customer-owned import or available corpus lane. Preserve the refusal and mark coverage unavailable.

For webhooks, inspect endpoint state and delivery history, validate the raw-body signature and deduplicate attempts. Correct the receiver before reactivation. Recover missed changes through authenticated event feeds. The [webhook guide](/guides/webhooks) covers rotation and history gaps.

Use the [error-code reference](/reference/errors) for status-specific handling, [common schemas](/reference/schemas) for response shapes, and the [documentation changelog](/changelog) when a newly documented route is absent from your server.