502 Bad Gateway Dijelaskan: Apa Artinya, Mengapa Terjadi, dan Cara Memecahkan Masalahnya

Kata Kunci

Glosarium singkat ini mencakup kata-kata infrastruktur yang paling mungkin menimbulkan kebingungan selama fase penjelasan lebih mendalam.

Mengapa Error 502 Terasa Sangat Mengganggu

Anda melakukan deployment, memuat ulang situs, dan domain merespons seketika — hanya saja bukan dengan aplikasi Anda. Atau pelanggan mengklik Checkout, halaman dimuat, dan transaksi gagal di balik pesan 502 Bad Gateway yang tegas. Itulah yang membuat error ini begitu menegangkan: situs dapat dijangkau, tetapi tidak cukup sehat untuk menyelesaikan handoff.

Sebuah 502 berada dalam kondisi tengah yang canggung. Ini tidak terlihat seperti hilang total, tetapi juga tidak berperilaku seperti layanan yang berfungsi. Bagi pengembang, ini bisa berarti deployment yang rusak atau rantai API yang bermasalah. Bagi pemilik bisnis, kepercayaan yang hilang atau pendapatan yang terganggu. Bagi tim, bagian terburuknya sering kali adalah kepemilikan: lapisan mana yang sebenarnya memiliki masalah ini?

Cara yang berguna untuk mendekatinya adalah dengan tidak menebak-nebak. Pertama, tentukan apa arti error tersebut. Kemudian petakan di mana ia berada dalam rantai permintaan. Kemudian selesaikan kegagalan secara logis, satu handoff pada satu waktu. Setelah Anda dapat melihat rantainya, error tersebut berhenti terlihat acak.

Apa yang Sebenarnya Dimaksud dengan 502 Bad Gateway

Error 502 Bad Gateway biasanya berarti server yang bertindak sebagai gateway atau proxy tidak dapat menggunakan respons yang diterimanya dari lapisan berikutnya di belakangnya. Dalam bahasa sederhana: satu server mencoba meneruskan permintaan Anda ke server lain, dan handoff tersebut gagal cukup parah sehingga server yang menghadap ke depan tidak dapat mengembalikan hasil yang normal.

📝 Catatan: Jika upstream mengembalikan error HTTP yang valid miliknya sendiri, proxy biasanya akan meneruskan error tersebut. Jika aplikasi mengembalikan 503 Service Unavailable yang nyata, lapisan depan seharusnya meneruskan 503 tersebut, bukan membuat 502. Sebuah 502 berarti respons itu sendiri tidak dapat digunakan. Jika tidak ada respons yang dapat digunakan yang tiba tepat waktu, itu sering kali menjadi 504.

Cara tercepat untuk berhenti salah membaca error 5xx adalah memisahkannya berdasarkan di mana kegagalan berada dan pertanyaan apa yang pertama kali dipicunya:

⚠️ Peringatan: Jangan menggabungkan 500, 502, 503, dan 504 ke dalam satu kelompok generik “server down”. Mereka menunjuk ke bentuk kegagalan yang berbeda, dan itu mengubah apa yang harus Anda periksa terlebih dahulu.

Setelah definisi tersebut jelas, pertanyaan berikutnya menjadi jauh lebih berguna: di mana dalam stack nyata handoff yang gagal ini sebenarnya terjadi?

Di Mana Error Terjadi dalam Rantai Permintaan Nyata

Sebagian besar permintaan modern tidak berjalan langsung dari browser ke aplikasi. Mereka melewati lapisan: browser ke CDN atau edge, edge ke reverse proxy atau load balancer, proxy ke proses aplikasi. Sebuah 502 menjadi terlihat di salah satu titik handoff tersebut.

Rantai permintaan yang disederhanakan: Browser → CDN/Edge → Reverse Proxy / Load Balancer → App / Process

Reverse proxy menerima permintaan publik dan meneruskannya secara internal. Load balancer melakukan hal serupa, tetapi dapat memilih di antara beberapa target yang sehat. Dalam kedua kasus, lapisan depan merutekan permintaan, bukan melakukan logika bisnis itu sendiri.

Analogi meja depan bekerja dengan baik di sini. Bayangkan proxy sebagai meja depan di gedung kantor. Ia memeriksa pengunjung, mencari kantor yang benar, dan mencoba menyerahkan pengunjung tersebut. Jika kantor tidak menjawab, menjawab di jalur yang salah, atau memberikan respons yang tidak dapat digunakan oleh meja depan, meja depan mengembalikan kegagalan tersebut. Itulah mengapa error yang terlihat sering muncul di lapisan proxy meskipun penyebab yang lebih dalam berada di tempat lain.

📝 Catatan: Proxy sering kali adalah pembawa pesan kegagalan, bukan penyebab aslinya.

“Server berikutnya” di balik meja depan tersebut dapat berupa layanan HTTP biasa pada sebuah port, listener aplikasi seperti 127.0.0.1:3000, atau proses berbasis socket lokal seperti PHP-FPM. Masalah akar tidak harus berada di proxy. Deployment yang buruk, worker aplikasi yang crash, atau bahkan kegagalan database dapat merusak backend cukup parah sehingga proxy hanyalah tempat 502 muncul ke permukaan.

Layanan edge menambahkan satu lapisan lagi. CDN seperti Cloudflare dapat meneruskan 502 dari sisi origin yang lebih dalam di stack Anda, atau dapat menghasilkan 502 sendiri ketika handoff edge-ke-origin gagal. Itulah mengapa “siapa yang mengembalikan error ini?” adalah pertanyaan praktis pertama, bukan renungan belakangan.

Mengapa Error 502 Terjadi: Kategori Kegagalan Utama

Setelah Anda berhenti memperlakukan 502 sebagai satu peristiwa misterius, lanskap penyebabnya menjadi jauh lebih mudah dikelola. Sebagian besar insiden masuk ke dalam tiga kelompok yang dapat digunakan kembali: upstream tidak tersedia, handoff itu sendiri salah konfigurasi, atau respons kembali dalam bentuk yang tidak dapat digunakan oleh gateway.

Kelompok pertama adalah yang paling jelas: upstream tidak ada dalam kondisi yang dapat digunakan. Mungkin aplikasi crash setelah deployment. Mungkin layanan tidak pernah dimulai ulang. Mungkin pool PHP-FPM mati, atau target ditandai tidak sehat dan dihapus dari rotasi. Ini adalah skenario “layanan down” klasik, tetapi hanya satu bagian dari lanskap 502.

Kelompok kedua adalah ketidakcocokan handoff. Di sini, kedua lapisan mungkin berjalan, tetapi mereka tidak sepakat tentang cara menjangkau satu sama lain. Proxy mungkin menunjuk ke port yang salah. Hostname mungkin diselesaikan secara tidak benar. Firewall mungkin memblokir jalur. Satu lapisan mungkin mengharapkan HTTPS sementara lapisan berikutnya hanya berbicara HTTP biasa. Jalur socket mungkin telah berubah. Dalam kasus ini, aplikasi bisa sehat dan koneksi antar lapisan masih rusak.

Kelompok ketiga lebih rumit: upstream menjawab, tetapi tidak dengan cara yang dapat digunakan oleh gateway. Target dapat mereset koneksi TCP, menutupnya terlalu awal, mengirim header yang cacat atau terlalu besar, atau mengembalikan output parsial di bawah beban. Aplikasi tidak sekadar “mati”; ia merespons cukup buruk sehingga gateway menolak apa yang diterimanya.

Ini juga mengapa 502 bukan hanya cerita tentang timeout. Beberapa kasus timeout menjadi 504 Gateway Timeout, bukan 502. Cloudflare dapat memunculkan 502 yang dihasilkan edge ketika konektivitas origin atau kompresi rusak. Load balancer dapat mengeluarkan 502 selama masalah timing deregistrasi atau kegagalan TLS handshake. “Layanan down” adalah satu kategori penyebab, bukan definisi dari error tersebut.

Model mental tersebut memberi Anda daftar periksa nyata sebelum Anda menyentuh file konfigurasi apa pun. Tanyakan kelompok mana yang kemungkinan besar Anda hadapi, lalu uji untuk bukti. Itulah yang membuat urutan pemecahan masalah terasa logis daripada ritualistik.

Urutan Pemecahan Masalah yang Cerdas untuk Error 502

Cara tercepat untuk memecahkan masalah 502 adalah mengidentifikasi lapisan mana yang mengembalikannya, kemudian menguji hop berikutnya di balik lapisan tersebut sebelum mengubah apa pun. Tujuannya adalah membuktikan di mana handoff yang gagal berada.

💡 Tips: Sebelum Anda memulai ulang atau mengedit apa pun, identifikasi siapa yang mengembalikan 502. Langkah atribusi yang bersih sering menghemat lebih banyak waktu daripada lima “perbaikan” pertama yang dicoba orang di bawah tekanan.

Fase 1: Identifikasi lapisan

Mulai dari sisi publik dan tanyakan apa yang sebenarnya dikembalikan oleh lapisan yang menghadap internet:

curl -I https://example.com

Ini menampilkan status HTTP dan header dari URL publik. Jika header jelas milik CDN, load balancer, atau reverse proxy, Anda memiliki petunjuk pertama. Jika halaman error bermerek Cloudflare, Cloudflare mungkin telah menghasilkan 502 itu sendiri; jika tidak bermerek, edge mungkin hanya meneruskan kegagalan dari sisi origin. Header seperti cf-error-type atau cf-error-origin dapat muncul di halaman error yang dihasilkan Cloudflare, yang berguna justru karena mereka tidak muncul di setiap 502.

📝 Catatan: Jika hanya satu pengunjung yang melihat error sementara yang lain dapat mengakses situs, pengaturan VPN, proxy, firewall, atau DNS lokal masih bisa menjadi bagian dari masalah. Sebuah 502 biasanya dari sisi server, tetapi jalur klien yang terisolasi dapat mengaburkan apa yang Anda amati.

Fase 2: Verifikasi jalur upstream

Setelah Anda mengetahui lapisan mana yang mengembalikan 502, uji hop berikutnya di belakangnya. Jika reverse proxy terlibat, konfirmasi bahwa layanan proxy dan backend keduanya berjalan, dan konfirmasi bahwa listener yang diharapkan ada:

systemctl status nginx
systemctl status <app-service>
ss -tlnp

Ganti <app-service> dengan nama layanan backend Anda. systemctl status memberi tahu Anda apakah proses proxy atau aplikasi hidup, gagal, atau sedang dimulai ulang. ss -tlnp menunjukkan apakah ada sesuatu yang benar-benar mendengarkan pada port yang Anda harapkan.

Kemudian uji apakah backend menjawab langsung tanpa proxy di tengah:

curl -i http://127.0.0.1:3000

Jika permintaan langsung berhasil tetapi URL publik masih mengembalikan 502, backend mungkin sehat dan handoff mungkin menjadi masalah nyata. Itu mengarahkan Anda ke pengaturan target proxy, ketidakcocokan protokol, hostname upstream, ekspektasi TLS, atau aturan firewall daripada kode aplikasi saja.

Fase 3: Gunakan perintah sebagai bukti, bukan seremoni

Setelah pemeriksaan langsung, beralih ke bukti yang menjelaskan mengapa handoff gagal:

journalctl -u nginx -u <app-service> --since "15 min ago"
dig +short example.com
nginx -t

Ketiga pemeriksaan ini menjawab pertanyaan yang berbeda. journalctl memunculkan crash terbaru, reset, petunjuk timeout, dan kegagalan terkait deployment. dig +short memberi tahu Anda apakah hostname yang Anda andalkan diselesaikan dengan cara yang diharapkan server. nginx -t memvalidasi sintaks reverse-proxy sebelum Anda memuat ulang apa pun, yang penting karena definisi upstream yang buruk dapat menghasilkan 502 bahkan ketika backend baik-baik saja.

Sinyal praktis biasanya terlihat seperti ini:

Itulah pola inti yang perlu diingat: identifikasi lapisan, verifikasi hop berikutnya, kemudian gunakan log dan pengujian langsung untuk menjelaskan ketidakcocokan. Bukti dulu. Pengaturan kemudian.

Bagaimana Jalur Pemecahan Masalah Berubah Berdasarkan Model Hosting

Langkah selanjutnya setelah 502 bergantung pada seberapa banyak stack yang Anda kendalikan. Logika pemecahan masalah tetap sama, tetapi jumlah yang dapat Anda periksa sendiri berubah banyak antara shared hosting, VPS, dedicated server, dan pengaturan edge-proxied.

📝 Catatan: Pada shared hosting, eskalasi bukan tanda menyerah. Ini sering kali merupakan langkah teknis yang benar karena lapisan yang paling penting untuk 502 mungkin berada di luar visibilitas Anda.

Pada shared hosting, hal paling berguna yang dapat Anda lakukan adalah mengumpulkan bukti: waktu, URL yang terpengaruh, apakah error konstan atau intermiten, dan apakah dimulai setelah deploy atau perubahan konfigurasi. Itu memberi dukungan sesuatu yang dapat ditindaklanjuti. Jika Anda tidak mengontrol reverse proxy, layanan aplikasi, atau log server, diagnosis lapisan demi lapisan yang bermakna berakhir dengan cepat.

Pada VPS, alur kerja penuh menjadi realistis karena Anda dapat memeriksa layanan, listener, log, dan konfigurasi proxy secara langsung. Di situlah pemecahan masalah reverse-proxy berada. Pada infrastruktur VPS AlexHost, memeriksa systemctl, journalctl, ss, target upstream, dan konfigurasi Nginx adalah bagian dari kepemilikan normal, bukan sesuatu yang selalu tersembunyi di balik dukungan.

Dedicated server memberi Anda visibilitas yang sama, tetapi dengan lebih banyak tanggung jawab. Anda memiliki lebih banyak stack penuh, dan mungkin lebih banyak asumsi jaringan sekitarnya juga. Jika Anda menambahkan CDN atau layanan edge lain di depan, pertanyaan kepemilikan pertama tetap sama: apakah edge menghasilkan 502, atau apakah ia meneruskan kegagalan dari sisi origin? Lebih banyak kontrol tidak membuat pemecahan masalah lebih sederhana secara default. Ini memberi Anda lebih banyak tempat untuk diperiksa.

Berpikir dalam Lapisan, Bukan dalam Kepanikan

Error 502 Bad Gateway berhenti terasa misterius setelah Anda memperlakukannya sebagaimana adanya: handoff antar server yang gagal, bukan peristiwa browser yang acak. Browser hanyalah tempat Anda menyadarinya. Cerita nyata berada di lapisan yang meneruskan permintaan ke lapisan berikutnya dan gagal mendapatkan kembali sesuatu yang dapat digunakan.

Jadi jaga urutannya tetap sederhana: identifikasi lapisan, periksa hop berikutnya, validasi dengan pengujian langsung dan log, dan ubah pengaturan hanya ketika bukti menunjuk ke suatu tempat yang spesifik. Jika insiden berulang terus mendorong Anda ke arah visibilitas log, proxy, dan layanan yang lebih dalam, itulah titik di mana lingkungan dengan kontrol lebih tinggi — termasuk VPS atau dedicated server AlexHost — menjadi berguna karena alasan operasional, bukan alasan pemasaran. Metode mengalahkan hafalan di sini.