Errors and recovery

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.

{
  "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 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

Cloud operations

Repository tools

HTTP and events

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