Idempotency

Outcome: Design or review Idempotency for this system while keeping data correct, secure, and easy to operate. User context: After a payment times out, a buyer retries with idempotency key `8f2…` and the same normalized request hash. The server returns the first charge instead of charging again. The same key with a different amount is rejected, and keys expire under a written policy. Technical concept or control: Idempotency. Why it fits: Make retries safe for unreliable networks, queues, payment calls, and systems that may deliver a message at least once. Do not use it when: `POST` is not always non-idempotent. An idempotency key also does not replace transactions, authorization, or conflict checks. Engineering requirements: Define inputs, outputs, contracts, and rules that must always hold. Set authorization and input checks. Define failures, timeouts, retries, one-time effects, data moves, and compatibility limits. Operations: Add useful signals and logs that hide sensitive data. Set capacity limits and write an operator guide. Test recovery and rollback. Acceptance criteria: Contract and failure-path tests pass. Data and authorization rules still hold during retries and partial failures. Check performance limits, monitoring, recovery, and rollback. Evidence and limits (evidence boundary): The standard covers only the listed scope. It does not choose the visual style, product decision, or Vibulary example. Unknowns to confirm: Where the code runs, data stores, traffic shape, consistency needs, and the security boundary. Also confirm the compatibility period, service goals, and rollback limits.