> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getarbol.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Retries and idempotency

> Retry Arbol API operations without duplicating calls, facts, contacts, or provider mutations.

Retry behavior is operation-specific. Read the operation description before replaying a mutation after a timeout or lost response.

## Safe retry policy

1. Retry side-effect-free reads with bounded exponential backoff and jitter.
2. For `429`, wait at least `data.retryAfterSeconds` when the response includes it.
3. Retry `503` only when the operation description says it is safe or the request has a stable idempotency key.
4. Do not retry other `4xx` responses unchanged.
5. Cap retries and surface the final `X-Request-Id` for support.

## Mutations

Some operations accept a domain `idempotencyKey`. Reuse the **same key with the same semantic input** after an uncertain response. Examples in the generated contract include starting an outbound conversation and, when supplied with a stable observation timestamp, asserting a fact.

If an operation has no idempotency key, read current state before replaying it. This applies to many creates, provider onboarding actions, and complete-set updates.

<Warning>
  A new idempotency key creates a new logical attempt. Generating a fresh key for every retry defeats idempotency.
</Warning>

## Optimistic revisions

Operations that accept `expectedRevision` use it to prevent lost updates. On `409`, use the returned current revision when available, fetch the resource again, and apply your change to the new state. Do not loop by replacing the revision without reconciling the data.