service_unavailable — Layanan sedang tidak tersedia

service_unavailable adalah kode error HTTP 503 pada Se-Hari API. Kami sedang tidak bisa melayani permintaan ini untuk sementara. Berbeda dari 500 yang berarti sesuatu rusak, 503 berarti sesuatu sedang tidak siap — dan biasanya akan siap lagi tanpa campur tangan Anda.

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

#Kapan ini muncul

503 berbeda dari 500 dalam hal yang penting untuk keputusan Anda: ia berarti sistem sedang tidak siap, bukan bahwa sesuatu rusak. Deploy yang sedang berjalan, komponen yang sedang dimuat ulang, atau pemeliharaan singkat semuanya menghasilkan kode ini, dan semuanya berakhir sendiri tanpa campur tangan siapa pun.

#Kenapa ini terjadi

• Pemeliharaan terjadwal
• Komponen internal sedang dimuat ulang setelah deploy
• Konfigurasi yang dibutuhkan endpoint tersebut sedang tidak terbaca

#Cara memperbaikinya

Coba lagi setelah jeda. Kalau ada header Retry-After, ikuti angkanya. Rancang workflow Anda supaya menahan pekerjaan sebentar alih-alih menganggapnya gagal permanen — 503 hampir selalu berumur pendek.

#Yang memicu error

# Menandai pekerjaan sebagai gagal permanen pada 503 pertama
if [ "$status" != "200" ]; then tandai_gagal; fi

#Yang seharusnya

# 503 ditahan, bukan digagalkan
case "$status" in
  200|201|202) selesai ;;
  503|502) jadwalkan_ulang_dalam 300 ;;
  4*) tandai_gagal ;;
esac

#Aman diulang?

Ya, ini kandidat retry terbaik di seluruh daftar. Jeda beberapa menit lalu coba lagi hampir selalu cukup. Tetap sertakan Idempotency-Key yang sama untuk berjaga-jaga kalau ternyata request sempat diproses sebagian.

#Jangan tertukar dengan

503 menyiratkan kesementaraan; 500 tidak. Kalau Anda hanya bisa menangani satu jenis retry, tangani 503 — ia hampir selalu berhasil pada percobaan berikutnya, sementara 500 yang berulang biasanya berarti ada sesuatu yang benar-benar perlu kami perbaiki lebih dulu.

#Mencegahnya terulang

Rancang workflow yang menahan pekerjaan alih-alih menggagalkannya. Jeda beberapa menit lalu coba lagi hampir selalu cukup. Yang perlu dihindari adalah menandai pekerjaan sebagai gagal permanen pada 503 pertama, karena itu mengubah gangguan berdurasi satu menit menjadi antrean pekerjaan yang harus diperbaiki manusia satu per satu.

#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 === 'service_unavailable') {
		// Coba lagi setelah jeda. Kalau ada header `Retry-After`, ikuti angkanya. Rancang workflow…
		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