unprocessable_entity — Bentuk benar, isinya tidak bisa diproses

unprocessable_entity adalah kode error HTTP 422 pada Se-Hari API. Body Anda lolos validasi bentuk, tapi isinya tidak masuk akal untuk dikerjakan. Ini lapisan pemeriksaan setelah validasi skema — yang memeriksa makna, bukan tipe.

#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": "unprocessable_entity",
    "message": "Contoh pesan untuk unprocessable_entity.",
    "docs_url": "https://se-hari.com/docs/error/unprocessable-entity",
    "request_id": "req_a1b2c3d4e5f6",
    "details": {
      "reason": "NO_AUDIO"
    }
  }
}

#Kapan ini muncul

Kode ini adalah lapisan pemeriksaan yang berjalan setelah bentuk request dinyatakan benar. Ia memeriksa makna, bukan tipe — dan karena itu ia sering menandai masalah pada data sumber, bukan pada kode Anda. Rekaman tanpa jalur audio adalah contoh paling umum, dan tidak ada yang bisa diperbaiki dari sisi request.

#Kenapa ini terjadi

• Rekaman yang diminta tidak punya jalur audio sama sekali
• Berkas rusak atau tidak selesai terunggah
• Durasi rekaman nol

#Cara memperbaikinya

Periksa berkas sumbernya sebelum mengantre ulang. Notulen dari rekaman tanpa audio tidak akan pernah berhasil, berapa kali pun diulang — bedakan kegagalan seperti ini dari kegagalan yang memang layak di-retry.

#Yang memicu error

# Mengulang terus rekaman yang memang tidak punya audio
curl -X POST "https://se-hari.com/api/v1/notes/<id>/retry" \
  -H "Authorization: Bearer $SEHARI_API_KEY"

#Yang seharusnya

# Periksa dulu apakah rekamannya punya aset audio
curl "https://se-hari.com/api/v1/recordings?limit=5" \
  -H "Authorization: Bearer $SEHARI_API_KEY" | jq '.data[] | {id, has_audio_asset}'

#Aman diulang?

Hampir selalu percuma. Kalau penyebabnya rekaman tanpa audio atau berkas rusak, tidak ada jumlah percobaan yang mengubah hasilnya. Periksa details.reason sebelum memutuskan mengulang.

#Jangan tertukar dengan

Berbeda dari invalid_request yang menolak berdasarkan bentuk, kode ini menolak berdasarkan isi — semua field ada dan tipenya benar, tapi datanya tidak bisa dikerjakan. Karena itu memperbaiki request tidak membantu; yang perlu diperbaiki adalah data sumbernya, atau pekerjaan itu memang tidak bisa dilakukan.

#Mencegahnya terulang

Bedakan kegagalan yang layak diulang dari yang tidak, dan jadikan itu percabangan eksplisit di workflow Anda. Payload webhook note.failed memuat field retryable justru untuk keperluan ini. Mengulang notulen yang gagal karena tidak ada audio akan gagal dengan cara yang sama persis setiap kali, sementara mengulang yang gagal karena kredit habis akan berhasil segera setelah top up.

#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 === 'unprocessable_entity') {
		// Periksa berkas sumbernya sebelum mengantre ulang. Notulen dari rekaman tanpa audio tidak…
		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