sxsphinxstack

Skills / Working / Implement idempotent requests

Working Code skill

Implement idempotent requests

Implement idempotent write requests that survive client retries, timeouts, concurrency, and process failure.

Bind one caller intent to one durable outcome, including a stable replayed response.

Procedure

  1. Define the operation's business effect, duplicate risk, and the point at which it becomes committed.
  2. Require a high-entropy idempotency key scoped to principal, tenant, endpoint, and operation class.
  3. Fingerprint the normalized request so reuse with different input becomes a conflict.
  4. Atomically reserve a new key and distinguish new, in-progress, completed, expired, and conflicting states.
  5. Commit the business mutation and durable result in one transaction or a recoverable state machine.
  6. Return the recorded status and body for a matching completed request.
  7. Define bounded waiting or retry guidance for an in-progress request.
  8. Retain keys for at least the credible retry window and expire them through a documented policy.
  9. Reconcile abandoned reservations and ambiguous downstream outcomes before allowing new effects.
  10. Test parallel duplicates, timeout-after-commit, crash points, changed payloads, expiry, and multi-instance execution.

Guardrails

  • Do not rely on an in-memory lock in a horizontally scaled service.
  • Never silently accept the same key for a materially different request.
  • Avoid expiring evidence before clients and downstream systems can finish credible retries.

Related skills

  • Implement idempotency — Implement idempotency for retried operations using stable request identity, atomic outcome storage, conflict rules, expiry, and recovery tests.
  • Implement oauth login — Implement standards-based federated login with validated identity claims, protected redirects, and safe account linking.
  • Implement graceful shutdown — Implement graceful shutdown that stops admission, drains work, preserves durable state, releases resources, and terminates within platform limits.