Idempotensi

Gunakan Idempotency-Key saat koneksi yang gagal membuat Anda tidak yakin apakah permintaan Anda berhasil. Jaminannya adalah penerimaan tepat satu kali: percobaan ulang dengan kunci yang sama dan permintaan yang identik harus menghasilkan satu operasi yang diterima dalam jangka waktu penyimpanan 3 jam, meskipun Anda kehilangan respons aslinya.

Cara kerja

Idempotensi bersifat opt-in. Tambahkan header Idempotency-Key pada permintaan POST, PATCH, PUT, atau DELETE yang didukung. Permintaan tanpa header ini diproses seperti biasa tanpa deduplikasi. Permintaan GET mengabaikan header ini.

Pada API pelanggan, mutasi bercakupan workspace dan organisasi mendukung pemutaran ulang respons yang dijelaskan di bawah. Operasi khusus pengguna, operasi tanpa cakupan yang tidak terautentikasi, dan stream mengabaikannya. Operasi dengan kontrak pemutaran ulang terpisah mendefinisikan perilakunya di halaman referensi masing-masing. Sebagai contoh, Membuat panggilan suara menyimpan snapshot penerimaan asli untuk percobaan ulang yang cocok saat Anda menyertakan kunci.

SDK menghasilkan kunci untuk setiap pemanggilan yang mengubah data dan menggunakannya kembali untuk percobaan ulang otomatis, termasuk pembuatan panggilan. Anda tidak perlu menyertakan kunci sendiri untuk percobaan ulang SDK otomatis. Sertakan kunci Anda sendiri jika satu operasi yang dimaksud mencakup beberapa pemanggilan SDK terpisah, misalnya percobaan ulang setelah aplikasi Anda di-restart. Contoh-contoh berikut menunjukkan kasus tersebut.

await bird.email.send(
  {
    from: "hello@yourdomain.com",
    to: ["delivered@messagebird.dev"],
    subject: "Welcome!",
    html: "<p>Thanks for signing up.</p>",
  },
  { idempotencyKey: "welcome-user/usr_abc123" },
);

client.email.send(
    from_="hello@yourdomain.com",
    to=["delivered@messagebird.dev"],
    subject="Welcome!",
    html="<p>Thanks for signing up.</p>",
    options={"idempotency_key": "welcome-user/usr_abc123"},
)

_, err := client.Email.Send(context.Background(), bird.EmailSendParams{
	From:    "hello@yourdomain.com",
	To:      []string{"delivered@messagebird.dev"},
	Subject: "Welcome!",
	HTML:    "<p>Thanks for signing up.</p>",
}, option.WithIdempotencyKey("welcome-user/usr_abc123"))

$bird->email->send(
    from: 'hello@yourdomain.com',
    to: ['delivered@messagebird.dev'],
    subject: 'Welcome!',
    html: '<p>Thanks for signing up.</p>',
    options: new RequestOptions(idempotencyKey: 'welcome-user/usr_abc123'),
);

curl -X POST https://us1.platform.bird.com/v1/email/messages \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: welcome-user/usr_abc123" \
  -d '{
    "from": "hello@yourdomain.com",
    "to": ["delivered@messagebird.dev"],
    "subject": "Welcome!",
    "html": "<p>Thanks for signing up.</p>"
  }'

Kunci adalah string tidak kosong dengan panjang hingga 255 karakter. Nilai header kosong melewati deduplikasi. Format yang direkomendasikan adalah kunci deterministik yang diturunkan dari entitas Anda sendiri, <event-type>/<entity-id> (misalnya welcome-user/usr_abc123), sehingga percobaan ulang lintas restart proses menggunakan kunci yang sama; UUID acak per operasi logis juga bisa digunakan. SDK Bird menghasilkan kunci UUID secara otomatis untuk setiap permintaan yang mengubah data dan menggunakannya kembali di seluruh percobaan ulang internalnya.

Kunci berlaku dalam cakupan workspace Anda, atau organisasi Anda pada endpoint tingkat organisasi. Respons yang sudah selesai disimpan selama 3 jam; percobaan ulang setelah jangka waktu tersebut dapat diproses sebagai permintaan baru. Jika hasil operasi asli belum diketahui setelah kedaluwarsa, anggap operasi tersebut belum terselesaikan dan rekonsiliasikan sebelum mengirim lagi.

Pemutaran ulang

Percobaan ulang yang cocok dalam tiga jam harus menghasilkan operasi asli. Jika responsnya disimpan, API mengembalikan kode status dan body yang sama tanpa menerima operasi lain. Respons hasil pemutaran ulang membawa satu header tambahan agar Anda dapat membedakannya dari pemrosesan baru:

HTTP/1.1 202 Accepted
Idempotency-Replay: true

Respons yang disimpan dapat mencakup penolakan 4xx. Gunakan kunci baru saat memperbaiki permintaan: jika penolakannya disimpan, percobaan ulang tanpa perubahan akan memutar ulang penolakan tersebut, dan permintaan yang diubah mengembalikan 409 E01005 IdempotencyKeyReuse. Respons 5xx tidak disimpan sebagai respons yang sudah selesai. Jaminan penerimaan tepat satu kali juga berlaku untuk percobaan ulang setelah error ini.

Mode kegagalan

Menggunakan kembali kunci yang sudah selesai dengan permintaan berbeda dianggap sebagai bug di sisi klien: Bird langsung mengembalikan 409 alih-alih diam-diam memberikan respons yang tidak sesuai dengan yang Anda kirim. Buat kunci baru untuk permintaan baru. Perbandingan mencakup metode, endpoint, parameter path dan query, serta body permintaan mentah, termasuk spasi JSON. Upload multipart membandingkan nama bagian, nama file, dan konten; boundary dan urutan bagian tidak memengaruhi pemutaran ulang.

RequestInProgress berarti permintaan bersamaan dengan kunci yang sama belum selesai, biasanya karena timeout sisi klien yang agresif memicu percobaan ulang saat percobaan pertama masih diproses. Tunggu sebentar, lalu coba lagi dengan kunci dan permintaan yang sama. Lihat Errors untuk format respons kesalahan yang membungkusnya.

Apa yang tidak di-cache

Respons 5xx tidak disimpan sebagai respons yang sudah selesai. Coba lagi dalam tiga jam dengan backoff terbatas, kunci yang sama, dan permintaan yang identik. Jaminan penerimaan tepat satu kali tetap berlaku meskipun respons asli hilang.

Jika perlindungan idempotensi tidak tersedia sebelum eksekusi, API mengembalikan 503 E01033 IdempotencyUnavailable tanpa mengeksekusi percobaan ini. Pertahankan kunci pada setiap percobaan ulang. Error ini tidak menjelaskan hasil dari percobaan sebelumnya dengan kunci yang sama.

Panduan praktis

• Buat satu kunci per operasi logis dan gunakan kembali untuk setiap percobaan HTTP dari operasi tersebut.
• Coba lagi saat terjadi error jaringan, timeout, dan 5xx dalam tiga jam dengan exponential backoff terbatas, dengan mempertahankan kunci dan permintaan yang identik.
• Biarkan hasil yang tidak diketahui tetap belum terselesaikan saat percobaan ulang habis atau masa penyimpanan kedaluwarsa. Lakukan rekonsiliasi sebelum mengirim operasi lain, baik dengan kunci lama maupun kunci baru.
• Untuk pengiriman pesan, periksa status pesan guna memastikan pengiriman setelah permintaan diterima.
• Perlakukan 409 IdempotencyKeyReuse sebagai bug dalam pembuatan kunci Anda. Jangan coba lagi.
• Kunci bersifat opsional pada mutasi. Gunakan kunci saat Anda membutuhkan perlindungan percobaan ulang; abaikan pada permintaan GET.

Langkah selanjutnya

• Referensi idempotensi API: skema header dan response-header
• Konsep SDK: pembuatan kunci otomatis dan perilaku coba lagi di SDK
• Errors: respons kesalahan dan katalog kode
• Mengirim email: endpoint send dan batch