Coba lagi dengan aman tanpa pemrosesan ganda
Jika Anda sudah mengirim permintaan tetapi tidak menerima respons, Anda mungkin perlu mengirimnya lagi. Sertakan pengidentifikasi percobaan ulang agar server dapat mengetahui apakah permintaan sudah diproses.
Jika Anda mengirim ulang pengidentifikasi dan isi permintaan yang sama, hasil awal dikembalikan tanpa menerbitkan kupon atau menambahkan stempel dua kali.
Cara menggunakan
Buat pengidentifikasi percobaan ulang yang unik untuk setiap operasi baru dan kirim melalui header Idempotency-Key. Gunakan kembali nilai yang sama hanya saat mencoba ulang operasi yang sama karena respons tidak diterima.
curl -X POST "https://api.vivoldi.com/api/coupon/v1/create" \
-H "Authorization: APIKEY {YOUR_API_KEY}" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-20260920-000412" \
-d '{
"nm": "$5 discount coupon",
"discTypeIdx": 458,
"disc": 5
}'
Jika header tidak dapat dikirim, gunakan kolom requestId pada isi permintaan. Jika keduanya dikirim, nilainya harus sama.
| Bidang | Deskripsi | Jenis |
|---|---|---|
Idempotency-Key |
Header HTTP. Gunakan 8–64 karakter berupa huruf ASCII, angka, serta . _ : -. Gunakan nilai berbeda untuk setiap operasi baru. |
string |
requestId |
Kolom pada isi permintaan. Dapat digunakan sebagai pengganti header dengan format yang sama. | string |
Cakupan penggunaan
Berlaku untuk pembuatan dan penukaran kupon, serta pembuatan, penambahan, pengurangan stempel, dan penukaran hadiah. API v2 untuk memperbarui kupon dan stempel juga mendukung pengidentifikasi percobaan ulang.
Pengidentifikasi ini opsional. Jika tidak dikirim, permintaan diproses seperti biasa. Catatan disimpan selama 72 jam; setelah itu, permintaan dengan nilai yang sama dapat dianggap sebagai operasi baru.
Pengidentifikasi dibedakan menurut organisasi dan jenis operasi. Jangan gunakan kembali satu nilai untuk operasi berbeda dalam organisasi yang sama.
Respons dan penanganan kesalahan
Jika permintaan yang sudah berhasil dicoba ulang dengan pengidentifikasi dan isi yang sama, hasil awal dikembalikan. Operasi dan webhook tidak dijalankan lagi.
Konflik menghasilkan HTTP 409 dengan code 409 pada isi respons. Periksa message untuk mengetahui penyebabnya. Meski HTTP 200, pastikan code bernilai 0.
| Situasi | HTTP | code |
Tindakan |
|---|---|---|---|
| Coba lagi dengan pengidentifikasi dan isi yang sama | 200 | 0 | Hasil awal dikembalikan. Tidak perlu tindakan lain. |
| Pengidentifikasi yang sama digunakan untuk isi berbeda | 409 | 409 | Gunakan pengidentifikasi baru untuk operasi baru. |
| Permintaan sebelumnya dengan pengidentifikasi yang sama masih diproses | 409 | 409 | Tunggu sebentar, lalu coba lagi dengan pengidentifikasi yang sama. |
| Nilai header dan requestId berbeda | 400 | 1213 | Samakan kedua nilai atau kirim salah satunya saja. |
| Format pengidentifikasi tidak valid | 400 | 1216 | Gunakan 8–64 karakter berupa huruf ASCII, angka, atau simbol . _ : - |
| Permintaan lain lebih dahulu mengubah item yang sama | 409 | 409 | Periksa status terbaru, lalu tinjau kembali permintaan Anda. |
Cara mencoba ulang dengan aman
- Pilih nilai seperti nomor pesanan yang dapat digunakan kembali saat mencoba ulang operasi yang sama. Nilai baru pada setiap percobaan tidak dapat dihubungkan dengan permintaan sebelumnya.
- Jika tidak menerima respons, coba lagi dengan pengidentifikasi dan isi permintaan yang sama. Jika isinya berubah, gunakan pengidentifikasi baru.
- Tindakan untuk HTTP 409 bergantung pada penyebabnya. Jika proses masih berjalan, coba lagi nanti. Jika pengidentifikasi digunakan ulang atau terjadi perubahan bersamaan, tinjau permintaan.