Idempotency-Key

Jaringan bisa putus setelah permintaan sampai di OngkirHub tetapi sebelum responsnya sampai di servermu. Kalau kamu mengulang POST /v1/shipments tanpa pengaman, bisa saja terbentuk dua pengiriman dan saldo terpotong dua kali. Header Idempotency-Key mencegahnya: permintaan ulang dengan kunci yang sama mendapat respons yang sama, tanpa diproses dua kali.

curl -X POST https://api.ongkirhub.com/v1/shipments \
  -H "Authorization: Bearer ohk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-INV-2026-10-0412" \
  -d @pengiriman.json

Aturan kunci

• Diterima di semua endpoint POST: POST /v1/rates, POST /v1/shipments, dan POST /v1/shipments/{id}/cancel. Endpoint GET mengabaikannya.
• Panjang 1 sampai 100 karakter, berisi huruf, angka, titik, titik dua, garis bawah, atau tanda hubung. Kunci dengan karakter lain ditolak dengan 400 invalid_request.
• Kunci berlaku per workspace dan per mode. Respons yang tersimpan berlaku 24 jam.
• Kunci yang baik berasal dari sistemmu dan unik untuk satu tindakan, misalnya nomor pesanan toko (order-INV-2026-10-0412) atau UUID yang kamu simpan bersama pesanan.

Kirim header ini di setiap POST /v1/shipments. Untuk POST /v1/rates dan pembatalan, header ini opsional tetapi tetap berguna saat kamu mengulang permintaan.

Cara kerjanya

Situasi	Respons
Kunci baru	Permintaan diproses seperti biasa, lalu responsnya disimpan.
Kunci dan isi sama, permintaan pertama sudah selesai	Respons yang tersimpan dikirim lagi dengan status yang sama, ditambah header Idempotent-Replayed: true. Tidak ada yang diproses ulang.
Kunci sama, permintaan pertama masih diproses	409 idempotency_conflict. Tunggu sebentar, lalu kirim ulang.
Kunci sama, isi berbeda	422 idempotency_key_reused. Pakai kunci baru untuk permintaan yang berbeda.

“Isi sama” berarti method, path, dan body JSON yang sama. Urutan field di body tidak berpengaruh.

Respons error 5xx dan 429 tidak disimpan. Kalau permintaan pertama mendapat salah satunya, ulangi dengan kunci yang sama dan permintaan akan diproses lagi. Respons error lain ikut disimpan, misalnya 422 validation_error, 402 wallet_insufficient_funds, dan 409 quote_expired. Setelah memperbaiki isinya, mengisi saldo, atau mengecek tarif lagi, kirim permintaan baru dengan kunci baru.

Pengaman tambahan di POST /v1/shipments

Untuk pembuatan pengiriman, OngkirHub juga menyimpan kunci bersama pengirimannya secara permanen:

• Setelah 24 jam, kunci yang sama dengan isi yang sama tetap tidak membuat pengiriman baru. Responsnya 201 berisi pengiriman yang sudah ada dengan status terbarunya, tanpa header Idempotent-Replayed. Isi yang berbeda ditolak dengan 409 idempotency_conflict.
• Satu kunci tidak bisa dipakai di mode test dan live sekaligus. Kunci yang sudah dipakai di satu mode ditolak di mode lain dengan 409 idempotency_conflict.
• Satu penawaran (quoteId) hanya bisa dipakai untuk satu pengiriman, kecuali pengiriman sebelumnya gagal. Mengirim penawaran yang sama dengan kunci lain atau tanpa kunci ditolak dengan 409 idempotency_conflict, dan details.shipmentId berisi pengiriman yang sudah memakai penawaran itu.

Dengan pengaman ini, klik ganda atau percobaan ulang tidak membuat resi ganda.

Ketiga penolakan itu dan penolakan karena permintaan pertama masih diproses memakai kode yang sama, 409 idempotency_conflict. Bedakan dari isinya:

Penyebab	Ciri	Yang perlu dilakukan
Permintaan pertama masih diproses	Tanpa details.shipmentId, hilang setelah beberapa detik	Tunggu sebentar, lalu ulangi dengan kunci dan isi yang sama.
Kunci sudah terikat ke pengiriman lain (mode lain, atau isi berbeda setelah 24 jam)	Tanpa details.shipmentId, tetap muncul setelah diulang	Jangan diulang. Periksa apakah pesanan ini sudah punya pengiriman. Pakai kunci baru hanya untuk pengiriman yang memang berbeda.
Penawaran sudah dipakai	Ada details.shipmentId	Ambil pengiriman di details.shipmentId. Kalau memang butuh pengiriman lain, cek tarif lagi untuk penawaran baru.

Pola percobaan ulang yang aman

1. Buat kunci sekali per tindakan dan simpan bersama pesananmu sebelum mengirim permintaan.
2. Kirim permintaan dengan kunci itu.
3. Kalau terjadi timeout, error koneksi, 5xx, 429, atau 409 idempotency_conflict tanpa details.shipmentId, tunggu sebentar lalu ulangi dengan kunci dan isi yang sama. Naikkan jeda tunggu setiap kali mencoba, dan berhenti setelah beberapa kali bila 409 tetap muncul.
4. Kalau mendapat 2xx, simpan id pengiriman dari respons. Header Idempotent-Replayed: true berarti respons ini hasil permintaan sebelumnya.
5. Jangan membuat kunci baru hanya untuk mengulang permintaan yang gagal karena timeout atau error sementara. Kunci baru dipakai setelah kamu mengubah isi permintaan, misalnya dengan penawaran baru.

Untuk 429, tunggu sesuai header Retry-After. Detail batas permintaan ada di Rate limit.