Idempotency
Retry aman untuk POST /v1/orders.
Kenapa
Agent sering mengulang request saat timeout atau koneksi putus. Tanpa idempotency, retry POST /v1/orders bisa membuat dua order dan memotong deposit dua kali. Kirim header Idempotency-Key dan retry dengan key yang sama tidak akan membuat order kedua.
Cara pakai
http
POST /v1/orders
Idempotency-Key: 5b8e0c1a-7f7e-4b61-9a53-3c1f0f1d2e11Buat key baru (UUID ideal) untuk setiap order yang berbeda, dan pakai key yang sama untuk setiap retry order itu. Di MCP, isi argumen idempotency_key pada tool buat_order.
Aturan
| Situasi | Hasil |
|---|---|
| Key baru | Diproses normal, 201 |
| Key sama, body sama, dalam 24 jam, request pertama sudah berhasil | 200 dengan header Idempotent-Replayed: true dan order yang sama (status terkini, bukan salinan saat dibuat) |
| Key sama, body berbeda, dalam 24 jam | 422 IDEMPOTENCY_KEY_REUSED. Pakai key baru |
| Request pertama ditolak (budget, deposit, validasi) | Tidak ada yang disimpan. Retry dengan key yang sama dievaluasi ulang |
| Lebih dari 24 jam | Key dianggap baru |
| Format key salah | 400 VALIDATION |
- Hanya berlaku untuk
POST /v1/orders. Endpoint POST lain belum mendukung idempotency. - Key berlaku per organisasi: dua organisasi boleh memakai key yang sama.
- Format: 1 sampai 255 karakter ASCII yang terlihat, tanpa spasi, tanda kutip, atau backslash. Nilai dalam tanda kutip (
"abc") diterima. - "Body sama" dibandingkan secara kanonis: urutan properti JSON tidak berpengaruh, tetapi nilai dan field harus sama persis (termasuk
callback_urldanmax_budget).
Request bersamaan
Kalau dua request dengan key yang sama datang bersamaan, keduanya bisa mulai diproses, tetapi hanya satu yang bisa menyimpan key. Transaksi yang kalah dibatalkan seluruhnya (ordernya juga), lalu request itu menjawab dengan replay order pemenang. Hasil akhirnya tetap satu order.
Catatan