Idempotency and retries

Key model

The client creates one unique key per logical operation and persists it until the terminal result is known. The server returns the same result for that operation instead of duplicating the business effect.

• Bind the key to tenant, endpoint, and operation identity.
• Persist a payload hash to prevent reuse with different data.
• Return a stable response or an explicit conflict.
• Choose TTL from domain risk, not only network timing.

Retry policy

Retry only transient failures with exponential backoff, jitter, and a bounded attempt count. Do not retry permanent 4xx or authorization failures.

delay = min(cap, base * 2^attempt) + random_jitter

Concurrency

The server must close race windows with an appropriate unique constraint or lock and a database transaction. A check-then-create sequence without atomic protection is not idempotent.