idempotency_key_reused — Idempotency-Key dipakai untuk isi yang berbeda

idempotency_key_reused adalah kode error HTTP 409 pada Se-Hari API. Anda mengirim Idempotency-Key yang sudah pernah dipakai, tapi dengan body yang berbeda. Kami menolaknya alih-alih menebak mana yang Anda maksud.

#Bentuk responsnya

Semua error Se-Hari memakai amplop yang sama. Yang perlu dicabang di kode Anda adalah code, bukan message — teks pesan bisa kami perbaiki sewaktu-waktu, sedangkan code adalah kontrak publik yang hanya berubah lewat versi API baru.

{
  "error": {
    "code": "idempotency_key_reused",
    "message": "Contoh pesan untuk idempotency_key_reused.",
    "docs_url": "https://se-hari.com/docs/error/idempotency-key-reused",
    "request_id": "req_a1b2c3d4e5f6",
    "details": {}
  }
}

#Kapan ini muncul

Kode ini melindungi Anda dari kesalahan yang tidak akan pernah Anda sadari tanpanya. Kalau kami menerima key yang sama untuk body berbeda dan mengembalikan hasil yang pertama, workflow Anda akan menganggap item kedua sudah dikerjakan padahal tidak — dan hasilnya adalah pekerjaan yang hilang tanpa satu pun error.

#Kenapa ini terjadi

• Key idempotensi tetap dipakai untuk request yang isinya berubah-ubah
• Key dibangun dari waktu dengan presisi kasar sehingga dua request berbeda mendapat key yang sama
• Loop memakai satu key untuk semua item

#Cara memperbaikinya

Bangun key dari identitas pekerjaannya, bukan dari waktu. Pola yang aman: {id-workflow}-{id-eksekusi}-{indeks-item}. Kalau Anda memang ingin mengerjakan sesuatu yang baru, pakai key yang baru.

#Yang memicu error

# Key tetap untuk body yang berbeda-beda
for id in rec1 rec2 rec3; do
  curl -X POST "https://se-hari.com/api/v1/notes" \
    -H "Idempotency-Key: batch-harian" \
    -H "Authorization: Bearer $SEHARI_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"recording_id\": \"$id\"}"
done

#Yang seharusnya

# Satu key per item
for id in rec1 rec2 rec3; do
  curl -X POST "https://se-hari.com/api/v1/notes" \
    -H "Idempotency-Key: batch-harian-$id" \
    -H "Authorization: Bearer $SEHARI_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"recording_id\": \"$id\"}"
done

#Aman diulang?

Percuma tanpa perubahan. Pakai key idempotensi baru untuk pekerjaan yang memang baru, atau kirim body yang sama persis kalau maksud Anda memang mengulang yang lama.

#Jangan tertukar dengan

Kalau permintaan Anda diulang dengan key DAN body yang sama persis, kami tidak menolaknya — kami mengembalikan hasil yang pertama, dengan status yang sama seperti aslinya. Kode ini hanya muncul kalau body-nya berbeda. Konflik data yang tidak melibatkan header ini muncul sebagai conflict biasa.

#Mencegahnya terulang

Bangun key dari sesuatu yang berkorespondensi satu-satu dengan pekerjaannya. Di n8n, {{$workflow.id}}-{{$execution.id}}-{{$itemIndex}} memenuhi syarat itu dan tetap stabil ketika n8n mengulang eksekusi yang gagal. Yang harus dihindari adalah key berbasis waktu dengan presisi kasar (misalnya per menit) dan key konstan per workflow, karena keduanya bisa bertabrakan untuk pekerjaan yang berbeda.

#Menangani ini di kode

Cabangkan pada error.code, dan bedakan kegagalan yang layak diulang dari yang tidak. Mengulang kegagalan yang tidak akan pernah berhasil hanya menghabiskan kuota rate limit — dan menyembunyikan kegagalan yang sebenarnya butuh perhatian Anda.

const res = await fetch('https://se-hari.com/api/v1/me', {
	headers: { Authorization: `Bearer ${process.env.SEHARI_API_KEY}` }
});

if (!res.ok) {
	const { error } = await res.json();

	if (error.code === 'idempotency_key_reused') {
		// Bangun key dari identitas pekerjaannya, bukan dari waktu. Pola yang aman…
		console.error(error.message, error.details);
	}

	// request_id adalah satu-satunya cara kami menemukan request ini di log.
	console.error(`request_id: ${error.request_id}`);
}

#Selanjutnya

• Semua kode error — daftar lengkap
• Autentikasi — scope dan siklus hidup API key
• Referensi API — error apa saja yang mungkin muncul di tiap endpoint