Contract 1.7.0 · Local previewRead Markdown

Errors

Reading a failure

Admission errors use HTTP status codes: invalid tokens return 401, missing scope 403, and exhausted grant limits 429 with Retry-After. Authentication challenges identify the protected resource or missing scope. OAuth uses its own protocol errors, such as invalid_grant and access_denied.

Tool failures carry isError=true and a structured Cadence error. The catalog’s HTTP status describes the error mapping; a completed MCP tools/call exchange can carry a tool error inside an HTTP 200 response. Do not treat HTTP 200 alone as a successful edit.

Error catalog

Code HTTP status Retryable Before retrying Meaning
invalid_input 400 yes after_change The input does not match the tool’s schema or rules. field_errors names each problem.
limit_exceeded 400 yes after_change The request asks for more than a contract limit allows, such as too long a date range or too large a result. Narrow the request.
not_found 404 no never No record with that id exists for this account.
conflict 409 yes after_refresh The record changed since it was read: expected_status or expected_revision is stale. Nothing changed.
idempotency_key_reused 409 yes after_change The idempotency_key was already used with a different input. Use a new key for a new request.
invalid_state 409 yes after_refresh The record’s current state does not allow this change.
authentication_required 401 yes after_authorization The access token is missing, expired, revoked, or issued for another resource. Reconnect Cadence.
insufficient_scope 403 yes after_authorization The connection does not include the permission this tool needs. required_scopes lists it.
rate_limited 429 yes after_delay Too many requests for this connection. Retry after retry_after_seconds.
service_unavailable 503 yes after_delay Cadence integrations are temporarily unavailable.
internal_error 500 yes after_delay Cadence could not complete the request. Nothing is assumed to have changed; retry once with the same idempotency_key.

Retrying safely

Read retry and retry_after_seconds. The retryable flag does not mean retry immediately. After conflict, reread the record and ask whether the intended edit still applies. Retry an uncertain write with the same idempotency_key and unchanged arguments. See idempotency and concurrency.

Never include tokens or returned note text in error reports. Inspector 2.11.0 has a known display issue with error structuredContent; see troubleshooting.