Aglet

Triage an API idempotency key collision

An idempotency key can protect a retry and still be wrong when two logical operations share it. Freeze one surprising result and record operation intent, key scope, client revision, and response correlation without exposing payload secrets. Separate retry, collision, and lost local linkage.

Establish what is happening

  1. Capture logical intent

    Record operation type, account or workspace, resource, request time, and a redacted payload fingerprint for one case. Keep the idempotency key in a protected label. Note whether the call was a retry after timeout or a new operation with similar input.

  2. Compare key and result

    Follow key generation, request storage, remote response, and local association. Compare key reuse window, payload fingerprint, and returned resource. A matching response may prove a safe retry; it does not prove that the key was unique for a separate operation.

  3. Bound collision candidates

    Group cases by key source, operation type, client revision, concurrency, and response class. Separate a real retry, low-entropy derivation, concurrent generation, and lost local key. Preserve unknown writes for review instead of sending another mutation.

What to carry forward

Triage ends when one operation’s identity, key lifecycle, returned result, and collision evidence are recorded. Stop ambiguous writes. Route key generation, local storage, and remote idempotency questions separately with the smallest safe readback. Keep ambiguous results behind review.

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