Header Idempotency-Key
Gunakan Idempotency-Key untuk mencoba lagi permintaan tanpa membuat operasi ganda. Jaminannya adalah penerimaan tepat satu kali: dalam masa penyimpanan 3 jam, percobaan ulang dengan key yang sama dan permintaan yang identik harus menghasilkan operasi asli, meskipun Anda kehilangan responsnya. Untuk strategi percobaan ulang, lihat Idempotensi.
Header permintaan
| Header | Ketentuan |
|---|---|
Idempotency-Key | Opsional. String tidak kosong dengan panjang hingga 255 karakter; UUID v4 disarankan. Berlaku pada operasi POST, PATCH, PUT, dan DELETE yang didukung; diabaikan pada GET, HEAD, dan OPTIONS. |
Mutasi dalam cakupan workspace dan organisasi mendukung pemutaran ulang respons yang dijelaskan di bawah. Operasi yang hanya berada dalam cakupan pengguna, operasi tanpa autentikasi yang tidak memiliki cakupan, dan stream tidak menggunakannya. Operasi dengan kontrak pemutaran ulang tersendiri menjelaskan perilakunya di halaman referensinya.
Jika header tidak disertakan atau nilainya kosong, permintaan diproses secara normal tanpa deduplikasi. Pada endpoint yang mendeklarasikan header ini, kunci yang lebih panjang dari 255 karakter mengembalikan 422 dengan kode E01001 ValidationError.
Kunci berlaku dalam cakupan workspace Anda, atau organisasi Anda untuk endpoint tingkat organisasi, dan disimpan selama sekitar 3 jam. Setelah masa penyimpanan berakhir, permintaan yang menggunakan kembali kunci diproses sebagai permintaan baru.
Semantik respons
| Skenario | Respons |
|---|---|
| Permintaan pertama dengan sebuah key | Diproses secara normal; respons yang sudah selesai dapat disimpan untuk diputar ulang; respons 5xx tidak disimpan. |
| Key sama, permintaan identik dalam masa penyimpanan | Operasi asli; respons yang disimpan diputar ulang dengan Idempotency-Replay: true. |
| Key sama, permintaan berbeda | 409 dengan E01005 IdempotencyKeyReuse. Buat key baru untuk permintaan baru. |
| Key sama, permintaan asli masih diproses | 409 dengan E01004 RequestInProgress. Tunggu, lalu coba lagi dengan key yang sama dan permintaan yang identik. |
Permintaan asli mengembalikan 5xx | Respons kesalahan tidak disimpan. Coba lagi dengan key yang sama dan permintaan yang identik. |
| Perlindungan idempotensi tidak tersedia sebelum eksekusi | 503 dengan E01033 IdempotencyUnavailable. Percobaan ini tidak dieksekusi; coba lagi dengan key dan permintaan yang sama. |
Respons yang di-replay identik byte per byte dengan aslinya (kode status sama, body sama), dibedakan hanya oleh header tambahan:
HTTP/1.1 202 Accepted
Idempotency-Replay: true"Identical request" mencakup metode, endpoint, parameter jalur dan kueri, serta isi mentah permintaan. Perbedaan pada nilai-nilai ini, termasuk spasi dalam JSON, memicu E01005. Unggahan multipart membandingkan nama bagian, nama file, dan isinya; batas dan urutan bagian tidak memengaruhi pemutaran ulang. Kedua kesalahan 409 dikembalikan dalam respons kesalahan standar.
Respons yang disimpan dapat mencakup penolakan 4xx. Gunakan kunci baru saat memperbaiki permintaan: jika penolakannya disimpan, percobaan ulang tanpa perubahan akan memutarnya ulang, sedangkan permintaan yang diubah mengembalikan 409 E01005 IdempotencyKeyReuse.
Jika terjadi timeout atau 5xx, coba lagi dengan backoff terbatas menggunakan key yang sama dan permintaan yang identik dalam tiga jam. Jaminan penerimaan tepat satu kali tetap berlaku meskipun respons asli hilang. E01033 IdempotencyUnavailable berarti percobaan ini tidak dieksekusi; ini tidak menjelaskan hasil percobaan sebelumnya. Pertahankan key pada setiap percobaan ulang.
Untuk pengiriman pesan, penerimaan tepat satu kali berarti satu pengiriman yang diterima untuk semua percobaan ulang yang cocok. Periksa status pesan untuk memastikan pengiriman. Setelah tiga jam, periksa hasil operasi asli sebelum mengirim lagi: key yang kedaluwarsa atau key baru dapat membuat operasi lain.
Perilaku SDK
SDK resmi melampirkan UUID Idempotency-Key yang dibuat otomatis ke setiap permintaan mutasi. UUID ini dibuat sekali per panggilan logis dan digunakan kembali di semua percobaan ulang panggilan tersebut. Anda dapat menyediakan key sendiri per panggilan (idempotencyKey di TypeScript, option.WithIdempotencyKey di Go, idempotency_key di Python, new RequestOptions(idempotencyKey: ...) di PHP) ketika satu operasi logis mencakup beberapa panggilan SDK. Untuk mendeteksi replay, baca header respons Idempotency-Replay melalui accessor transport-metadata setiap SDK: .withResponse() di TypeScript, option.WithResponseInto di Go, dan with_raw_response di Python.
Terkait
- Konsep idempotensi: strategi coba lagi, desain key, dan batas replay
- Respons kesalahan: respons kesalahan yang membungkus
E01004danE01005 - Pesan email: endpoint pengiriman, tempat paling umum menggunakan key
- Konsep SDK: pembuatan key otomatis dan percobaan ulang
Sumber daya terkait
Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini.