internal_error — Kesalahan di sisi kami

internal_error adalah kode error HTTP 500 pada Se-Hari API. Sesuatu gagal di dalam sistem kami. Request Anda mungkin sudah sebagian dikerjakan atau tidak sama sekali — itulah kenapa Idempotency-Key penting justru untuk kasus ini.

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

#Kapan ini muncul

Ini kode yang paling menuntut kehati-hatian dari sisi Anda, karena ia tidak memberi tahu apakah pekerjaan Anda sempat dikerjakan sebagian. Meeting mungkin sudah terbuat di Zoom sementara pencatatannya di sisi kami gagal; atau tidak ada apa pun yang terjadi. Dari luar, keduanya terlihat sama persis.

#Kenapa ini terjadi

• Bug yang belum kami temukan
• Kegagalan sementara pada komponen internal

#Cara memperbaikinya

Coba lagi dengan Idempotency-Key yang sama seperti request pertama. Kalau pekerjaannya ternyata sudah sempat selesai, Anda mendapatkan hasilnya alih-alih pekerjaan kedua. Kalau berulang, laporkan dengan menyertakan request_id — tanpa itu kami tidak bisa menemukan kembali request Anda di log.

#Yang memicu error

# Retry dengan key baru tiap kali = pekerjaan ganda kalau yang pertama ternyata berhasil
curl -X POST "https://se-hari.com/api/v1/meetings" -H "Idempotency-Key: $(uuidgen)" ...

#Yang seharusnya

KEY=$(uuidgen)

for percobaan in 1 2 3; do
  status=$(curl -s -o /tmp/b -w '%{http_code}' -X POST \
    "https://se-hari.com/api/v1/meetings" \
    -H "Idempotency-Key: $KEY" \
    -H "Authorization: Bearer $SEHARI_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"title":"Rapat","date":"2026-09-01","start_time":"09:00","pricing_tier_id":"..."}')
  [ "$status" = "500" ] || break
  sleep $((percobaan * 5))
done

#Aman diulang?

Ya, dengan Idempotency-Key yang SAMA. Ini krusial: request mungkin sudah sebagian dikerjakan. Key yang sama membuat kami mengembalikan hasil yang pertama alih-alih membuat duplikat. Key baru pada kode ini adalah cara paling umum menciptakan meeting ganda.

#Jangan tertukar dengan

Bedanya dengan upstream_error (502): kode ini berarti yang gagal adalah kami, sedangkan 502 berarti yang gagal adalah layanan pihak ketiga yang kami panggil. Bedanya dengan service_unavailable (503): 503 berarti kami sedang tidak siap dan akan siap lagi, sedangkan kode ini berarti sesuatu benar-benar tidak berjalan sebagaimana mestinya.

#Mencegahnya terulang

Selalu kirim Idempotency-Key pada operasi yang mengubah keadaan, dan gunakan key yang SAMA saat mengulang. Inilah satu-satunya cara membedakan kedua kemungkinan di atas: kalau pekerjaannya ternyata sudah selesai, request kedua mengembalikan hasilnya alih-alih membuat duplikat. Retry dengan key baru pada 500 adalah cara paling umum menciptakan meeting ganda yang kreditnya terpotong dua kali.

#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 === 'internal_error') {
		// Coba lagi dengan `Idempotency-Key` yang **sama** seperti request pertama. Kalau…
		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