Jaringan gagal di tempat terburuk: setelah server bertindak, tetapi sebelum Anda menerima jawabannya. Idempotency key membuat retry menjadi aman.
Cara kerjanya
Klien membuat key unik untuk satu aksi yang dimaksud dan mengirimkannya bersama request. Server menyimpan key itu bersama hasilnya. Jika key yang sama datang lagi, server mengirim ulang hasil yang tersimpan alih-alih bertindak lagi.
Working group IETF HTTPAPI sedang menstandarkan ini sebagai request header Idempotency-Key (draf 08, Oktober 2026, belum menjadi RFC). Draf itu menggambarkan key sebagai “a unique value generated by the client which the resource uses to recognize subsequent retries of the same request” (terjemahan: nilai unik yang dibuat klien, yang dipakai resource untuk mengenali retry berikutnya dari request yang sama) dan merekomendasikan UUID atau ID acak serupa. Kasus error dalam draf:
| Situasi | Status |
|---|---|
| Key tidak ada padahal wajib | 400 Bad Request |
| Request asli masih diproses | 409 Conflict |
| Key dipakai ulang dengan body berbeda | 422 Unprocessable Content |
Builders’ Library dari AWS menyampaikan hal yang sama dari sisi klien: “APIs with side effects aren’t safe to retry unless they provide idempotency.” (terjemahan: API yang punya efek samping tidak aman untuk di-retry kecuali menyediakan idempotensi.)
Kenapa ini penting
Retry dengan exponential backoff adalah praktik standar, dan banyak SDK melakukan retry otomatis. Tanpa idempotensi, retry setelah timeout bisa membuat dua pesanan atau dua tagihan. Dengan key, retry aman apa pun yang dilakukan percobaan pertama. Itulah yang menjadikannya alat inti bagi agen dan skrip yang membeli, memesan, atau membuat sesuatu tanpa diawasi manusia.
Di BroadNet Inference
BroadNet memakai pola ini untuk pembelian kunci per jam. POST /portal/keys/hourly menerima request_id di body JSON, dan dokumentasinya menyatakan “Idempotency is required for money safety” (terjemahan: idempotensi wajib demi keamanan uang):
curl -X POST https://inference.broadnet.ai/portal/keys/hourly \
-H "Authorization: Bearer <portal-credential>" \
-H "Content-Type: application/json" \
-d '{"request_id":"order-20260920-001","label":"kiosk-1"}'
Memakai ulang request_id tidak membuat atau menagih key lain. Setelah timeout, koneksi terputus, 409 mint_in_progress, atau 5xx, lakukan retry dengan request_id yang sama. Replay mengembalikan already_issued: true dan alias key-nya; hanya respons sukses pertama yang berisi key mentah. Dokumentasinya menyebut: “Never generate a replacement id until the original result is known.” (terjemahan: Jangan pernah membuat id pengganti sebelum hasil aslinya diketahui.)
BroadNet tidak mendokumentasikan idempotency key untuk /v1/chat/completions atau transkripsi. Lihat kode error dan retry untuk apa yang perlu di-retry di sana, dan rate limit untuk alasan retry membabi buta bisa memperparah 429.