Konsep inti

Idempotency-Key

Setiap permintaan non-GET wajib membawa header Idempotency-Key berupa UUID. Ini yang membuat jaringan rumah sakit yang tidak stabil tidak menghasilkan SEP ganda.

Kirim ulang permintaan dengan kunci yang sama dan body yang sama persis, dan Anda menerima respons yang identik, disertai header Idempotency-Replayed: true. Tidak ada pemanggilan kedua ke BPJS.

Pengulangan

POST /v1/bpjs/sep
Idempotency-Key: 00000000-0000-4000-8000-000000000001

→ 201  Idempotency-Replayed: true
       Idempotency-Original-Request-Id: req_01J9F3K2M7QX1041

Dua galat duplikat yang sering tertukar

Kode	Artinya	Tindakan
GW_IDEMPOTENCY_KEY_REUSED	Kunci sama, body berbeda. Biasanya karena kunci dipakai ulang untuk kunjungan lain, atau body ikut berubah saat dicoba lagi.	Perbaiki kode
GW_SEP_DUPLICATE	Kunci baru, tetapi kombinasi peserta, tanggal, dan jenis pelayanan sudah punya SEP aktif. Ini penjaga bisnis, bukan galat teknis: dua operator dengan dua kunci berbeda tetap tidak boleh menerbitkan SEP kedua.	Ambil SEP lama

Batas yang perlu diketahui

Body di atas 1 MiB — ditolak dengan GW_PAYLOAD_TOO_LARGE.
Respons di atas 256 KiB — tetap diproses, tetapi tidak disimpan untuk pengulangan; pengiriman ulang dengan kunci yang sama menghasilkan GW_IDEMPOTENCY_NOT_REPLAYABLE.
Respons 5xx tidak disimpan — sehingga kunci yang sama boleh dicoba lagi setelah kegagalan upstream.
Bila penyimpanan idempotensi tidak terjangkau — permintaan tulis ditolak dengan 503 GW_IDEMPOTENCY_UNAVAILABLE. Ini disengaja: SEP ganda lebih merugikan daripada permintaan yang gagal.