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

# Idempotency

> Use idempotency keys to make automation runs safe under retries, prevent duplicate side effects, and design workflows that converge to a consistent result.

Networks drop packets, clients retry, and queues redeliver. Without idempotency, the same user intent can create duplicate charges, tickets, or posts. Idempotency keys make “exactly-once behavior” practical on “at-least-once” infrastructure.

## Why it matters

Retries can duplicate side effects without idempotent design. Payment and ticketing integrations are the usual victims—duplicate idempotency keys should return the original result, not create a second record.

### Scope

Decide whether keys are global, per-tenant, or per-user. Collisions across tenants are rare but catastrophic if namespaces overlap.

## Keys

Supply a stable idempotency key derived from natural identifiers—order ID, request UUID, or hash of canonical fields. Avoid keys that change when unrelated whitespace changes.

### Rotation

If you must rotate key material, dual-write during transition and document the overlap window.

## Storage

Record processed keys long enough to cover your retry window plus clock skew. Expire old keys to bound storage, but not before your longest plausible retry storm.

### Conflicts

When a new payload arrives with an existing key but different body, reject loudly—something is inconsistent and needs human review.