conflict — Bentrok dengan kondisi data saat ini

conflict adalah kode error HTTP 409 pada Se-Hari API. Permintaan Anda sah, tapi ada sesuatu yang sudah menempati posisi itu. Ini bukan kegagalan — di banyak kasus, details justru berisi id data yang sebenarnya Anda cari.

#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": "conflict",
    "message": "Contoh pesan untuk conflict.",
    "docs_url": "https://se-hari.com/docs/error/conflict",
    "request_id": "req_a1b2c3d4e5f6",
    "details": {
      "note_id": "c0ffee00-1111-2222-3333-444455556666"
    }
  }
}

#Kapan ini muncul

Kode ini paling sering bukan kegagalan, melainkan jawaban. Ketika sebuah workflow mengantre notulen untuk rekaman yang sudah punya notulen, yang sebenarnya diinginkan pemanggil hampir selalu adalah notulen yang sudah ada itu — dan details memuat id-nya. Memperlakukan 409 sebagai kesalahan fatal berarti membuang informasi yang sudah diberikan.

#Kenapa ini terjadi

• Rekaman sudah punya notulen; satu rekaman hanya boleh punya satu
• URL webhook yang sama sudah terdaftar untuk akun ini
• Batas jumlah endpoint webhook atau API key aktif sudah tercapai

#Cara memperbaikinya

Baca details sebelum memperlakukan ini sebagai error. Untuk POST /notes, details.note_id adalah notulen yang sudah ada untuk rekaman tersebut — biasanya itulah yang ingin Anda ambil, bukan membuat yang baru.

#Yang memicu error

# Mengantre ulang rekaman yang sudah punya notulen
curl -X POST "https://se-hari.com/api/v1/notes" \
  -H "Authorization: Bearer $SEHARI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"recording_id": "c0ffee00-1111-2222-3333-444455556666"}'

#Yang seharusnya

# Cari rekaman yang memang belum punya notulen
curl "https://se-hari.com/api/v1/recordings?has_note=false&limit=10" \
  -H "Authorization: Bearer $SEHARI_API_KEY"

#Aman diulang?

Biasanya tidak perlu diulang sama sekali. Baca details — di sana ada id data yang sudah menempati posisi itu, dan itu biasanya yang Anda cari. Mengulang hanya akan menghasilkan 409 yang sama.

#Jangan tertukar dengan

Bedanya dengan idempotency_key_reused — yang juga 409 — terletak pada penyebabnya: kode itu soal header Idempotency-Key yang dipakai untuk isi berbeda, sedangkan kode ini soal data yang memang sudah ada. Bedanya dengan forbidden juga tegas: 403 berarti operasinya tidak diizinkan sama sekali, 409 berarti operasinya sah tapi sudah pernah dilakukan.

#Mencegahnya terulang

Rancang alur Anda supaya menanyakan kondisi sebelum membuat: GET /recordings?has_note=false mengembalikan tepat rekaman yang belum diproses, sehingga 409 tidak pernah perlu terjadi. Untuk webhook, gunakan GET /webhooks sebelum mendaftarkan URL baru. Pola ini lebih murah daripada menangani konflik, dan jauh lebih mudah dibaca oleh orang yang mewarisi kode Anda.

#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 === 'conflict') {
		// Baca `details` sebelum memperlakukan ini sebagai error. Untuk `POST /notes`…
		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