Aglet

Verify safe API retries with idempotency keys

A retry check must prove that one logical operation remains one effect while separate operations remain separate. Exercise success, lost response, concurrent creation, process restart, and key-generation failure. Inspect returned resource identity and local state instead of counting only responses.

Check whether the outcome improved

  1. Define operation identity

    Write expected key, payload fingerprint, resource, attempt count, and final state for one operation and for two similar operations. State which failures permit retry, which require readback, and which remain unknown. Keep secret material out of fixtures and logs.

  2. Exercise retry and race cases

    Run a successful mutation, a delayed response after timeout, two concurrent operations, and a process restart before retry. Confirm one operation reuses its key and distinct operations do not. Check the local record links each result to the right intent.

  3. Test key failure handling

    Remove or corrupt key storage, use a duplicate key label, and simulate a response after the client gives up. Verify the integration pauses or requests reconciliation rather than generating an unrelated mutation. Retain correlation evidence for every ambiguous result.

What to carry forward

Accept when retries preserve one logical effect, distinct operations never share identity, and unknown results stop at a safe readback or review. Keep verification partial for remote key retention outside the fixture. Record key policy, operation cases, and client revision.

Technical background: Stripe documentation.

Keep the decision with the work.

Use a Work Item in Aglet to record the problem, the evidence you have, and the next decision. Add an owner and priority, then keep updates in the discussion so the next person can follow the reasoning.

Create an account See the product workflow