Idempotency And Ambiguous Outcomes

A client can lose the response after the server commits, making retry necessary even though the original outcome is unknown.

Why This Matters

Idempotency turns repeated delivery of one logical operation into one durable business result.

Working Model

A client can lose the response after the server commits, making retry necessary even though the original outcome is unknown. Correctness comes from preserving an explicit invariant across every permitted ordering, not from expecting one observed timing.

Practical Rules

  • Generate keys at the operation boundary.
  • Bind keys to the authenticated scope and request fingerprint.
  • Store status and result durably.
  • Handle concurrent first use atomically.
  • Define retention and misuse behavior.

Failure Modes

  • Using a random new key for each retry.
  • Caching keys only in one PHP process.
  • Returning the first result for a different payload.
  • Assuming idempotency makes every operation commutative.

Verification

  • Drop responses after commit.
  • Send concurrent requests with one key.
  • Reuse a key with another payload.
  • Verify one side effect and repeatable result.

What You Should Be Able To Do

After this lesson, you should be able to explain idempotency keys, ambiguous transport outcomes, deduplication, and durable result replay, choose a suitable approach for a real PHP project, and verify the result instead of relying on assumptions.

Practice

Practice: Design An Idempotency Record

Define stored fields for payment creation.

Your answer must:

  • state the intended outcome;
  • show the commands, data flow, or implementation shape;
  • identify at least one unsafe alternative;
  • explain how the result will be verified.
Show solution

Store owner scope, key, request hash, state, durable business ID, response summary, timestamps, and expiry under a unique scoped key.

The important part is not memorising one command or vendor screen. The solution makes the invariant, failure behavior, and verification evidence explicit.

Practice: Handle Concurrent First Use

Two workers receive the same new key simultaneously.

Your answer must:

  • state the intended outcome;
  • show the commands, data flow, or implementation shape;
  • identify at least one unsafe alternative;
  • explain how the result will be verified.
Show solution

Use a unique insert or transactional lock so one owns processing. The other observes pending or completed state rather than executing the charge.

The important part is not memorising one command or vendor screen. The solution makes the invariant, failure behavior, and verification evidence explicit.

Practice: Reject Key Reuse

A key is reused with a changed amount.

Your answer must:

  • state the intended outcome;
  • show the commands, data flow, or implementation shape;
  • identify at least one unsafe alternative;
  • explain how the result will be verified.
Show solution

Compare a canonical request fingerprint and return a conflict without executing. Log safe identifiers, not sensitive payment data.

The important part is not memorising one command or vendor screen. The solution makes the invariant, failure behavior, and verification evidence explicit.