Safe retry: idempotency key để retry một request không biến thành hai lần charge
Trong hệ phân tán, retry là mặc định — client, gateway, load balancer, queue consumer đều retry khi timeout hoặc lỗi tạm thời. Vấn đề là nhiều thao tác quan trọng không idempotent tự nhiên: một request POST /charges gửi hai lần thì trừ tiền khách hai lần, một message OrderCreated xử lý hai lần thì ship hai đơn. Idempotency key là cơ chế để server nhận diện "cùng một intent" giữa các lần retry và chỉ thực hiện side effect một lần, trong khi vẫn trả về response giống hệt cho mọi lần gọi lặp — về mặt hiệu ứng thấy được từ bên ngoài, đây là cái người ta hay gọi là "exactly-once effect" (dù ở tầng transport vẫn là at-least-once).
Cơ chế hoạt động
Client sinh một identifier duy nhất cho mỗi thao tác (thường là UUIDv4) và đính kèm request — quy ước phổ biến là HTTP header Idempotency-Key (Stripe API dùng đúng tên này, và IETF có draft draft-ietf-httpapi-idempotency-key-header chuẩn hoá cùng tên header). Server dùng key làm identity của thao tác trong một cửa sổ TTL:
Nhận request với key K.
