Retry behavior is operation-specific. Read the operation description before replaying a mutation after a timeout or lost response.
Safe retry policy
- Retry side-effect-free reads with bounded exponential backoff and jitter.
- For
429, wait at least data.retryAfterSeconds when the response includes it.
- Retry
503 only when the operation description says it is safe or the request has a stable idempotency key.
- Do not retry other
4xx responses unchanged.
- 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.