Rangkaian gagal di tempat yang paling teruk: selepas pelayan bertindak tetapi sebelum anda menerima jawapan. Kunci idempotensi menjadikan cubaan semula selamat.
Cara ia berfungsi
Klien mencipta kunci unik untuk satu tindakan yang dikehendaki dan menghantarnya bersama permintaan. Pelayan menyimpan kunci itu bersama hasilnya. Jika kunci yang sama tiba lagi, pelayan memainkan semula hasil yang disimpan dan tidak bertindak sekali lagi.
Kumpulan kerja IETF HTTPAPI sedang menyeragamkan ini sebagai pengepala permintaan Idempotency-Key (draf 08, Oktober 2026, belum menjadi RFC). Ia menerangkan kunci itu sebagai “a unique value generated by the client which the resource uses to recognize subsequent retries of the same request” (Terjemahan BroadRouter: “nilai unik yang dijana oleh klien yang digunakan oleh sumber untuk mengenal pasti cubaan semula seterusnya bagi permintaan yang sama”) dan mengesyorkan UUID atau ID rawak yang serupa. Kes ralat dalam draf itu:
| Situasi | Status |
|---|---|
| Kunci tiada apabila diperlukan | 400 Bad Request |
| Permintaan asal masih diproses | 409 Conflict |
| Kunci diguna semula dengan badan berbeza | 422 Unprocessable Content |
Builders’ Library AWS membuat perkara yang sama dari sisi klien: “APIs with side effects aren’t safe to retry unless they provide idempotency.” (Terjemahan BroadRouter: “API yang mempunyai kesan sampingan tidak selamat dicuba semula melainkan ia menyediakan idempotensi.”)
Mengapa ia penting
Cubaan semula dengan backoff eksponen ialah amalan standard, dan banyak SDK mencuba semula secara automatik. Tanpa idempotensi, cubaan semula selepas tamat masa boleh mencipta dua pesanan atau dua caj. Dengan kunci, cubaan semula selamat walau apa pun yang dilakukan oleh cubaan pertama. Ini menjadikannya alat teras untuk ejen dan skrip yang membeli, menempah atau mencipta sesuatu tanpa manusia memerhati.
Di BroadNet Inference
BroadNet menggunakan corak ini untuk membeli kunci sejam. POST /portal/keys/hourly menerima request_id dalam badan JSON, dan dokumentasinya menyatakan “Idempotency is required for money safety” (Terjemahan BroadRouter: “Idempotensi diperlukan untuk keselamatan wang”):
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"}'
Menggunakan semula request_id tidak mencipta atau mengenakan caj untuk kunci lain. Selepas tamat masa, sambungan terputus, 409 mint_in_progress atau 5xx, cuba semula dengan request_id yang sama. Main semula memulangkan already_issued: true dan alias kunci; hanya respons berjaya yang pertama mengandungi kunci mentah. Dokumentasinya menyatakan: “Never generate a replacement id until the original result is known.” (Terjemahan BroadRouter: “Jangan sekali-kali menjana id pengganti sehingga hasil asal diketahui.”)
BroadNet tidak mendokumenkan kunci idempotensi untuk /v1/chat/completions atau transkripsi. Lihat kod ralat dan cubaan semula untuk perkara yang patut dicuba semula di sana, dan had kadar untuk sebab cubaan semula membuta tuli boleh memburukkan 429.