REST mutations that require idempotency accept Idempotency-Key: 1–200 printable ASCII characters. Retain the same key for retries of the same uncertain request with identical input. Use a new value for a genuinely new action.
Revision-guarded mutations also require If-Match with the opaque revision from ETag or a job result. If a revision is missing or stale, read the current resource and review the change before retrying. MCP expresses these values as operation_id and expected_revision.
A mutation may return 200 for a terminal job or 202 while work remains. For 202, use the returned Location and Retry-After. Do not construct a polling URL from an unrelated site address. Job responses can include pollAfterSeconds.
Terminal states are succeeded, partially_failed, failed and cancelled. Report the actual state and inspect result metadata; receiving a job identifier is not evidence of success.
REST errors contain error.code and error.requestId. Rate-limited responses include Retry-After. Honor it and avoid immediate retry loops. Unknown fields, duplicate query keys and fields shadowing path variables are rejected.
When access fails, inspect the configured workspace, key status and permitted scopes. Do not silently switch to another user's credentials. A denied MCP tool may be absent from discovery because the catalog is filtered by current capabilities.
For support, retain the request ID and operation name. Exclude authorization headers, API keys, temporary upload capabilities and personal recipient data from logs or support messages.