Skip to main content
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, honor a returned Retry-After header and any documented data.retryAfterSeconds. A retry delay is a minimum wait, not permission to repeat an unsafe mutation.
  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.
A new idempotency key creates a new logical attempt. Generating a fresh key for every retry defeats idempotency.

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

​
Network and service boundaries

A timeout, disconnected client or 5xx response can arrive after a downstream operation has already committed. Retrying from a different process or through MCP does not create a new idempotency guarantee. The owning API operation determines whether the same key and input can be replayed. For a safe retry, keep a bounded attempt count and total deadline, add jitter to exponential backoff, and stop when the operation returns a permanent validation or authorization refusal. Keep the request reference from each attempt so support can distinguish the original uncertain outcome from later retries. Never log credentials or mutation payloads as retry diagnostics.