Troubleshoot agents, MCP, and REST
401 authentication failure
Section titled “401 authentication failure”Confirm the client uses /agent/v2 or /mcp/v2 and a credential authorised after the durable cutover. Check the Authorization: Bearer header, expiry, revocation status, environment-variable availability, and whether a password reset revoked the credential. Agent endpoints reject mixed cookie and bearer authentication.
Tool is missing
Section titled “Tool is missing”MCP catalogs are scope-filtered. Review the credential’s immutable scopes. Create a replacement credential if more authority is intentionally required.
403 forbidden
Section titled “403 forbidden”The token may be valid while a live check fails: verified email, membership, seat, admin role, resource ownership, scope, or controlled-account grant.
409 conflict
Section titled “409 conflict”- Version conflict: read the current workflow, run, or effect state.
IDEMPOTENCY_KEY_REUSED: the key was used for a different request identity.IDEMPOTENCY_REQUEST_IN_PROGRESS: keep the same request and key; do not create another operation.- Effect digest conflict: one stable effect key was reused with different request bytes; save corrected source and start a new run.
MCP caller error
Section titled “MCP caller error”Every mutating tool needs caller.name, caller.version, and idempotencyKey. Do not rely on MCP initialize metadata for the caller label.
REST caller error
Section titled “REST caller error”Mutations need Txcast-Agent-Name, Txcast-Agent-Version, and Idempotency-Key headers. Reads do not.
Temporary external failure
Section titled “Temporary external failure”Respect retryable and retryAt, especially for Sourcify, Safe Transaction Service, and RPC rate limits. Preserve the correlation ID and same idempotency key for an uncertain mutation.