Header Idempotency-Key
API Bird mendukung deduplikasi permintaan opsional melalui header Idempotency-Key. Halaman ini menjelaskan kontrak HTTP; 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 | Status dan body asli di-replay, dengan header respons 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. Lock kedaluwarsa dalam ~30 detik; tunggu lalu coba lagi. |
| Permintaan asli mengembalikan 5xx | Tidak di-cache: key terbuka dan percobaan ulang diproses sebagai permintaan baru. |
| 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:
Contoh kode
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.
Respons 5xx tidak pernah di-cache. Coba lagi dengan backoff menggunakan key dan permintaan yang sama. E01033 IdempotencyUnavailable berarti percobaan ini tidak dieksekusi; ini tidak menjelaskan hasil percobaan sebelumnya. Pertahankan key pada setiap percobaan ulang.
Sebuah operasi dapat berlaku sebelum responsnya disimpan. Jika respons itu hilang, atau lock in-flight kedaluwarsa, percobaan ulang dapat mengeksekusi operasi tersebut lagi. Timeout atau respons 5xx lainnya tidak membuktikan bahwa operasi tidak berdampak.
Perilaku SDK
SDK resmi melampirkan UUID Idempotency-Key yang dibuat otomatis ke setiap permintaan mutasi, 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) 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: envelope yang membungkus E01004 dan E01005
- 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. Sumber daya tersedia dalam bahasa Inggris.
Pahami konsepnyaShould I use a Bird SDK or call the API directly?Ikuti jalur pembelajaranBuild your first integrationPanduan implementasiSend your first email
Dapatkan ringkasan implementasi