Idempotency & retries
One logical mutation, one retained request key.
For an operation marked Idempotency-Key required in the API reference, use one browser- or server-generated UUID for one logical mutation.
If the result is ambiguous, retry the same operation, path, normalized body, and Idempotency-Key. Do not generate a fresh key merely because a response was lost. A replay may return the first committed response, including a one-time API key or Webhook signing secret, subject to current authorization and replay retention.
Changing the target Project or Workspace, name, body, or key turns the request into a different attempt. A reused key with a different fingerprint can be rejected. Idempotency possession does not bypass current Project or Account membership.
The private repository SDK can automatically generate a fresh key for one marked call. That convenience does not make two separate calls an idempotent retry: for ambiguity, your application must explicitly retain and reuse its key. The SDK does not automatically retry for you.
Some operations, such as Billing Checkout, protect an external provider execution under the same public request key. The caller still supplies only the original BusinessMode path, body, and key; provider-specific execution details remain backend-owned.
Not every mutation has this durable contract. Follow the operation's OpenAPI extension and documented behavior. For example, assign a machine seat requires a key, whereas release a machine seat does not. Do not automatically replay uncertain non-idempotent mutations without first checking canonical state.