Lab: get charged three times for one order

The payment cards lesson said an Idempotency-Key is required on order, and required is easy to read as bureaucratic. This shows what the header is actually preventing, which is the most ordinary failure in distributed systems: a response that never arrived.

1. 1

   Model a charge endpoint with and without idempotency, then retry the way a client does after a timeout.

   bash Copy

   cat > /tmp/idem.py <<'EOF'
   charges, seen = [], {}
   
   def charge(amount, key=None):
       if key is not None:
           if key in seen:
               return f"replayed, no new charge (total {sum(charges)})"
           seen[key] = True
       charges.append(amount)
       return f"charged {amount} (total {sum(charges)})"
   
   print("no key: the response timed out twice, so the client retried twice")
   for _ in range(3):
       print("  ", charge(25))
   
   charges.clear(); seen.clear()
   print("\nwith a key: same three attempts")
   for _ in range(3):
       print("  ", charge(25, key="order-abc-123"))
   EOF
   python3 /tmp/idem.py

2. 2

   Three attempts, one order, and a seventy-five dollar difference.

   text Copy

   no key: the response timed out twice, so the client retried twice
      charged 25 (total 25)
      charged 25 (total 50)
      charged 25 (total 75)
   
   with a key: same three attempts
      charged 25 (total 25)
      replayed, no new charge (total 25)
      replayed, no new charge (total 25)

3. 3

   Clean up.

   bash Copy

   rm /tmp/idem.py

The client was not buggy. A timeout tells you the response did not arrive and tells you nothing about whether the server acted, so retrying is the correct behaviour and the only safe way to do it is to make the second attempt recognisable as the same request.

• The key must be generated by the caller and reused across retries of one logical operation. Generating a fresh key per attempt is the same as having none.
• 1Claw scopes replay protection to a 24-hour window and compares a hash of the body, so the same key with a different body is a conflict rather than a silent replay.
• This is why an agent doing anything irreversible needs a stable key: an agent that retries on error is an agent that will eventually retry a purchase.