502 Bad Gateway Nedir?
Kısa tanım
502 Bad Gateway, ağ geçidi ya da proxy olarak çalışan bir sunucunun, isteği karşılamak için başvurduğu arkadaki (upstream) sunucudan geçersiz bir yanıt aldığını bildiren HTTP durum kodudur. Hatayı genellikle Nginx, CDN veya yük dengeleyici gibi bir ara katman üretir; asıl sorun ise çoğu zaman kapanmış, yeniden başlatılan ya da yanlış adreste dinleyen uygulama sunucusundadır.
Diğer adları: HTTP 502, 502 hatası, Bad Gateway hatası, hatalı ağ geçidi
Hatayı kim üretiyor, sorun nerede?
Modern bir web sitesinde istek, tarayıcıdan doğrudan uygulamaya gitmez. Arada çoğu zaman bir CDN, bir reverse proxy (sıklıkla Nginx) ve en sonda Node.js, PHP-FPM ya da Python gibi bir uygulama süreci bulunur. 502 yanıtını üreten, bu zincirin ortasındaki aracıdır: RFC 9110'a göre aracı sunucu, arkasındaki sunucudan geçersiz bir yanıt almıştır.
Bu ayrım teşhisin anahtarıdır. 502 gördüğünüzde Nginx ya da CDN büyük ihtimalle sağlıklıdır; yanıt veremeyen, onun arkasındaki katmandır. Bu nedenle uygulama koduna bakmadan önce hangi aracının hatayı verdiğini bulmak gerekir.
En sık görülen nedenler
- Uygulama süreci ayakta değil: Çökmüş, bellek yetersizliği nedeniyle işletim sistemi tarafından sonlandırılmış ya da deployment sırasında yeniden başlıyor.
- Yanlış upstream adresi: Nginx'in yönlendirdiği port veya Unix soketi, uygulamanın gerçekte dinlediği adresle uyuşmuyor.
- Bağlantının erken kapanması: Uygulama yanıtı yazmaya başlamadan bağlantıyı kesiyor.
- Geçersiz yanıt başlıkları: Proxy'nin kabul ettiği sınırı aşan çerez ya da başlık boyutu.
- CDN ile origin arasında sorun: Güvenlik duvarı CDN'in IP adreslerini engelliyor veya TLS ayarları eşleşmiyor.
Nginx hata kaydı genellikle nedeni açıkça söyler:
connect() failed (111: Connection refused) while connecting to upstream
upstream prematurely closed connection while reading response header from upstream
upstream sent too big header while reading response header from upstream502, 500 ve 504 arasındaki çizgi
500, uygulamanın kendisinin "bir şeyler ters gitti" demesidir. 502'de uygulama ya hiç cevap vermemiş ya da anlaşılmaz bir cevap vermiştir. 504 Gateway Timeout ise aracının arkadaki sunucuya ulaştığını ama yanıt için belirlenen süre dolana kadar beklediğini gösterir. Kabaca: 502 "cevap bozuk ya da yok", 504 "cevap gecikti" demektir.
Teşhis sırası
- Hata sayfasının kaynağını belirleyin. Cloudflare, origin'den gelen 502'yi kendi markalı sayfasıyla gösterir; markasız boş bir sayfa ise hatanın Cloudflare tarafında oluştuğuna işaret eder.
- Proxy'nin hata kaydında ilgili zamandaki satırları okuyun.
- Uygulamanın süreç durumunu ve son yeniden başlatma zamanını kontrol edin; hata bir deployment ile mi başladı?
- Uygulamaya proxy'yi atlayarak doğrudan istek gönderin:
curl -I http://127.0.0.1:3000/
Deployment anlarında kısa süreli 502'leri önlemenin yaygın yolu, yeni sürümü ayağa kaldırıp sağlık kontrolünden geçtikten sonra trafiği ona çevirmektir; blue-green deployment bu yaklaşımın sistemli hâlidir. Güvenlik açısından ise hata sayfasının iç IP adreslerini, sunucu sürümünü veya yığın izini göstermediğinden emin olun.
Arama motorları 502'yi nasıl karşılar?
Google, 502'yi diğer 5xx yanıtları gibi değerlendirir: yanıtla gelen içeriği yok sayar ve siteyi tarama hızını geçici olarak düşürür. Dizindeki URL'ler bir süre korunur; ancak hata kalıcı hâle gelirse bu URL'ler dizinden çıkarılır. Birkaç dakikalık bir kesinti iz bırakmaz; günlerce süren ya da her gece tekrarlayan 502'ler ise hem kullanıcı kaybına hem de tarama sorunlarına yol açar. Ayrıntılar Google'ın HTTP durum kodları belgesinde yer alır.