Aglet

Prioritize API idempotency key collisions

A collision on a harmless read is different from one that can create a second charge, record, or state transition. Prioritize by effect, concurrency, key reach, and whether the original result is known. Do not rotate keys indiscriminately while unknown writes remain unreconciled.

Decide where the work belongs

  1. Map side-effect exposure

    List operation, resource, key label, attempt history, and local state for each candidate. Separate reads, safe retries, unknown writes, and confirmed duplicate effects. Use returned identifiers and timestamps rather than treating similar payloads as duplicate proof.

  2. Choose safe containment

    Compare pausing writes, enforcing operation-scoped keys, performing readback, or routing to owner reconciliation. Record which actions are reversible and which require authority. A key fix without a recovery plan can leave existing unknown operations unresolved.

  3. Set collision order

    Queue confirmed duplicate effects and unknown writes first, then concurrent key generation and isolated false positives. Set owner, evidence threshold, and review time. If key storage is missing, prioritize restoring correlation evidence before changing remote request behavior.

What to carry forward

Return a collision queue with operation effect, identity evidence, containment, reconciliation owner, and proof needed to reprioritize. Escalate unknown or irreversible writes. Keep the rank provisional when remote key lifetime or result lookup is unavailable.

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