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.