# Jobs, retries and errors

## Mutations and revisions

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`.

## Asynchronous work

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.

## Handling failures

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.