sxsphinxstack

Skills / Working / Implement idempotency

Working Code skill

Implement idempotency

Implement idempotency for retried operations using stable request identity, atomic outcome storage, conflict rules, expiry, and recovery tests.

Return the same committed outcome without repeating the side effect.

When to use

  • Use for payments, orders, provisioning, notifications, jobs, webhooks, or mutations retried across failures.
  • Do not derive keys from timestamps or reuse one key for semantically different requests.

Procedure

  1. Define the operation boundary, side effects, caller identity, duplicate window, and committed outcome.
  2. Choose a client or server key scoped to tenant, operation, and normalized request.
  3. Store key, request fingerprint, processing state, result, and expiry in an atomic durable record.
  4. Claim new work atomically and reject the same key with a conflicting fingerprint.
  5. Return the recorded result for completed duplicates and a defined response for in-progress work.
  6. Coordinate external effects with transactions, outbox, provider idempotency, or reconciliation.
  7. Define crash recovery, stale processing, retention, cleanup, and replay-safe observability.
  8. Test simultaneous duplicates and failures before, during, and after every effect.

Related skills

  • Implement graceful shutdown — Implement graceful shutdown that stops admission, drains work, preserves durable state, releases resources, and terminates within platform limits.
  • Implement idempotent requests — Implement idempotent write requests that survive client retries, timeouts, concurrency, and process failure.
  • Implement distributed tracing — Implement distributed tracing with interoperable context propagation, useful spans, safe attributes, and measurable sampling.