Errors and recovery

Read the error code before retrying. Access and configuration refusals need a change first; an unknown observation is a check result, not a request failure. HTTP failures return an error object. MCP tool failures set isError and carry shared error information in text content. Optional details explain recovery when available.

{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "Access requires watches:read.",
    "requestId": "req_example",
    "details": { "scope": "watches:read" }
  }
}

This example shows a scope refusal. Keep its code and request identifier in diagnostics; keep credentials out. Server failures withhold private details. Configuration refusals such as PROVIDER_NOT_CONFIGURED include retryable: false and action: operator_configuration_required. Follow the named operator action; retrying cannot configure the server.

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	Fix the interrupted upload, then follow the operation’s retry rules

See HTTP setup and MCP setup. 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, checking a placement and batch verification.

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 gives end-to-end recovery; common schemas explains result fields and uncertainty. Availability distinguishes source contracts from your connected release.

Overview

MCP, CLI and API commands

CLI client

HTTP and events

Optional local workflows

Access and input

Checks, limits and replay

Expired history and configuration

​Access and input

​Checks, limits and replay

​Expired history and configuration

Access and input

Checks, limits and replay

Expired history and configuration