> ## 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.

# Errors and recovery

> Read shared error codes, distinguish retries from access or configuration changes, and recover queued work, expired cursors and missing evidence.

HTTP failures return an error object with a stable code and a message. Optional details carry recovery information when available. MCP tool failures set `isError` and return the shared error information in text content. Treat an error separately from a successful check whose observation is `unknown`.

```json theme={null}
{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "Access requires watches:read.",
    "details": { "scope": "watches:read" }
  }
}
```

This is an illustrative scoped-access refusal. Keep the code and relevant identifiers in diagnostics, while keeping credentials out of logs. Server failures use a public message and withhold private error details. Configuration failures can return `retryable: false` and `action: operator_configuration_required`.

## Access and input

| Code                                          | HTTP status | Recovery                                                                                           |
| --------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------- |
| `UNAUTHORIZED`, `GRANT_REVOKED`               | 401         | Supply a valid credential or reconnect the MCP grant                                               |
| `INSUFFICIENT_SCOPE`                          | 403         | Read the required scope and request access within your membership and project grant                |
| `WORKSPACE_DENIED`, `WORKSPACE_ACCESS_DENIED` | 403         | Verify workspace selection and current membership                                                  |
| `READ_ONLY_MEMBER`                            | 403         | Use a read operation or have an authorized member perform the write                                |
| `PILOT_ACCESS_REQUIRED`                       | 403         | Verify the account has pilot access                                                                |
| `INVALID_JSON`                                | 400         | Send a JSON object, with valid UTF-8 and JSON syntax                                               |
| `JSON_REQUIRED`                               | 415         | Set `Content-Type: application/json`                                                               |
| `BODY_TOO_LARGE`                              | 413         | Reduce the body below the 256 KiB request limit and respect the operation's row limit              |
| `BODY_TIMEOUT`                                | 408         | Retry the intended request with its original idempotency value after fixing the interrupted upload |

See [HTTP setup](/guides/connect-http) and [MCP setup](/guides/connect-mcp). Access errors need a corrected identity or grant; repeated identical requests cannot widen permissions.

## Checks, limits and replay

| Code                             | HTTP status | Recovery                                                                                                      |
| -------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------- |
| `IDEMPOTENCY_CONFLICT`           | 409         | Restore the original arguments for a retry; use a new value only for a different intended request             |
| `WATCH_BUSY`                     | 409         | Read the existing job identified in error details before requesting new work                                  |
| `WATCH_PAUSED`                   | 409         | Resume the watch only if recurring monitoring is intended, then request the check                             |
| `CHECK_COOLDOWN`                 | 429         | Wait until the check cooldown has passed; avoid polling admission                                             |
| `CHECK_QUOTA_EXCEEDED`           | 429         | Inspect current allowance and reservations before planning more checks                                        |
| `WATCH_QUOTA_EXCEEDED`           | 429         | Review active watch usage before enrolling another placement                                                  |
| `RATE_LIMITED`                   | 429         | Follow `Retry-After` when returned                                                                            |
| `BATCH_VERIFICATION_UNAVAILABLE` | 503         | The server needs the batch database migration and release; use available single verification when appropriate |

A 429 can describe a request-rate limit or an exhausted allowance. Read its code before scheduling a retry. See [usage](/reference/commands/get_usage), [checking a placement](/guides/check-placement) and [batch verification](/guides/import-and-verify).

## Expired history and configuration

`CURSOR_EXPIRED` returns 410 when a cursor falls outside retained history. Follow its recovery details. A source-event refusal provides `resync_required`, `snapshot_endpoint` and `resume_cursor`; export the current snapshot before resuming. Keep destination and source feeds separate. A missing historical interval cannot be reported as no changes.

`EVIDENCE_EXPIRED` returns 410 when the raw observation snapshot has expired. Observation metadata remains available. A new check produces current evidence, not a recreation of the old page.

`PROVIDER_NOT_CONFIGURED`, `PROVIDER_DISABLED`, `OWNED_DISCOVERY_NOT_CONFIGURED` and `OWNED_CORPUS_UNAVAILABLE` require operator configuration. Repeated calls cannot activate a provider or load a corpus. Use an available customer import when it fits the task.

Consult the operation's page for its remaining domain-specific errors. [Troubleshooting](/guides/troubleshooting) gives end-to-end recovery; [common schemas](/reference/schemas) explains result fields and uncertainty. [Availability](/capability-status) distinguishes source contracts from your connected release.