Content-Type: application/json and Idempotency-Key, a unique intent identifier of 16–128 letters, digits, underscores or hyphens. Generate it once, persist it in your integration, and reuse it with exactly the same request for retries. Generate a new identifier for each intentional new action, even when its arguments are identical.
Successful operation results are retained for seven days. A completed retry returns the original result with Idempotency-Replayed: true; current resource state may since have changed. Never reuse an old key after retention. externalReference provides durable draft correlation after operation retention and is unique within the workspace and integration principal. Key rotation preserves that principal. An independently created key or a different MCP grant is a different integration.
Retry policy
Retry transient network/502/503/504 errors with exponential backoff, preserving the key and payload for writes. Resolve validation, authorization and state conflicts before retrying. A 429 response requires waiting forRetry-After. For STALE_RESOURCE_VERSION, fetch and review the latest state before creating a new intent. For OPERATION_EXPIRED, reconcile the resource before deciding whether to repeat an action. See API errors for the complete recovery table.
The TypeScript SDK documents its automatic retry policy.