500 vs 502 vs 503: Bedah Error Server

Tiga cara dapur bisa gagal

Kembali ke analogi restoran. 500: koki salah racik dan masakan gosong (bug di kode server). 502: pelayan berteriak ke dapur tapi tidak ada yang menjawab (server depan tidak bisa menghubungi server belakang). 503: restoran tutup sementara untuk bersih-bersih, ada papan "buka lagi jam 2" (maintenance terjadwal). Tiga-tiganya "salah server", tapi penyebab dan responsnya beda.

Kenapa membedakannya penting

Untuk tim backend, kode yang tepat mempercepat diagnosis: 500 berarti cek log aplikasi, 502 berarti cek koneksi antar layanan, 503 berarti cek jadwal maintenance. Untuk frontend, responsnya juga beda: 500 tampilkan "coba lagi nanti", 502 bisa dicoba ulang otomatis (mungkin hanya glitch sesaat), 503 tampilkan hitung mundur dari header Retry-After.

Contoh 1: 500 karena bug aplikasi

GET /api/total-belanja HTTP/1.1
Host: toko.contoh.id

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{"error": "Terjadi kesalahan di server"}

Di log server tertulis detailnya (misalnya database timeout), tapi ke klien hanya pesan umum. Frontend:

if (response.status >= 500) {
  tampilkanPesan("Server sedang bermasalah, coba lagi beberapa saat.");
}

Contoh 2: 502 dan 503 di arsitektur berlapis

Setup umum: Nginx (depan) meneruskan ke aplikasi Node.js (belakang). Aplikasi crash:

HTTP/1.1 502 Bad Gateway

Nginx sehat, tapi tidak bisa menghubungi aplikasi. Solusinya di infrastruktur, bukan di kode. Sedangkan maintenance terjadwal:

HTTP/1.1 503 Service Unavailable
Retry-After: 300

{"error": "Maintenance sampai 14:00 WIB"}

Frontend bisa membaca Retry-After dan menampilkan "kembali dalam 5 menit" plus tombol coba lagi otomatis.

Kesalahan umum

Salah: menampilkan detail error 500 ke user. Stack trace membocorkan struktur kode ke publik. Yang benar: log detail di server, pesan umum ke klien.

Salah: mengembalikan 500 untuk masalah yang sebenarnya 4xx. Misalnya validasi gagal tapi kode melempar exception tak tertangani. Yang benar: tangani error yang bisa diprediksi dengan status 4xx yang tepat.

Salah: tidak punya halaman maintenance untuk 503. User mengira website rusak permanen. Yang benar: halaman maintenance yang ramah dengan estimasi waktu kembali.

Salah: retry 500 tanpa batas. Sama seperti modul error handling: retry hanya dengan backoff dan batas maksimal.

Template respons frontend untuk 5xx

Satu pola untuk semua error server di frontend:

function pesanServerError(status) {
  if (status === 503) return "Layanan sedang maintenance. Coba lagi beberapa menit.";
  if (status === 502) return "Server tidak merespons. Mencoba ulang otomatis...";
  return "Terjadi kesalahan di server. Tim kami sudah diberi tahu.";
}

Tiga pesan berbeda untuk tiga situasi berbeda, semuanya menenangkan dan memberi arah. Jangan pernah menampilkan "Error 500" mentah: angka itu untuk developer, bukan untuk user yang panik melihat pesanannya hilang.

Catatan teknis: Di platform seperti Vercel atau Cloudflare, kamu mungkin melihat 502/503 dari edge network mereka, bukan dari aplikasimu. Pelajari dashboard provider-mu untuk membedakan error edge vs error aplikasi.