İnternette gezinirken karşılaşılan hata mesajları arasında 502 Bad Gateway, hem kullanıcıları hem de web yöneticilerini en çok rahatsız eden türlerden biridir. Bir web sitesine erişmeye çalışırken tarayıcınızın size beyaz bir ekran ve bu soğuk mesajı göstermesi, ilk bakışta ne yapacağınızı bilememenize yol açabilir. Oysa bu hatanın arkasında yatan nedenler oldukça sistematiktir ve büyük çoğunluğu belirli adımlarla çözüme kavuşturulabilir. Bu makalede 502 hatasını kökeninden itibaren ele alıyor, hem sunucu yöneticilerine hem de sıradan kullanıcılara yönelik kapsamlı çözüm yöntemlerini paylaşıyoruz.
502 Bad Gateway Hatası Nedir?
HTTP 502 durum kodu, bir sunucunun ağ geçidi (gateway) veya proxy rolü üstlendiği durumlarda, bu sunucunun kendisine bağlı olan upstream (kaynak) sunucudan geçersiz ya da anlaşılamayan bir yanıt aldığında tarayıcıya ilettiği hata kodudur. HTTP standartlarını tanımlayan RFC 7235 belgelerine göre bu kod, “kötü ağ geçidi” anlamına gelir ve iletişimin zincirin ortasında koptuğunu simgeler.
Bunu daha somut bir örnekle açıklamak gerekirse: Bir kullanıcı tarayıcısından bir web sitesine istek gönderir. Bu istek önce bir ters proxy sunucusuna (örneğin Nginx veya bir CDN) ulaşır, oradan web uygulama sunucusuna (örneğin PHP-FPM, Node.js veya bir API servisi) iletilir. Eğer bu son halka ya yanıt vermiyorsa ya çökmüşse ya da beklenen formatta bir yanıt döndüremiyorsa, proxy sunucu kullanıcıya 502 hatasını iletir. Yani hata, son kullanıcının tarayıcısında değil; sunucular arasındaki iletişimde yaşanmaktadır.
502 hatasını 503 (Service Unavailable) ve 504 (Gateway Timeout) hatalarından ayırt etmek önemlidir. 503 sunucunun geçici olarak hizmet dışı olduğunu, 504 ise yanıtın zamanında gelmediğini ifade eder. 502’de ise yanıt gelmiştir; ancak bu yanıt geçersiz veya bozuktur.
502 Bad Gateway Hatasının Nedenleri
502 hatasının tetiklendiği senaryolar oldukça geniş bir yelpazeye yayılır. Bu nedenleri anlamak, doğru çözüme hızlı ulaşmak açısından kritik öneme sahiptir.
Upstream sunucunun çökmesi veya yeniden başlatılması, en yaygın nedenler arasındadır. PHP-FPM, Gunicorn, Puma gibi uygulama sunucuları beklenmedik bir hata karşısında çökebilir ya da sistem güncellemeleri sırasında kısa süreli yeniden başlatma döngüsüne girebilir. Bu pencerede gelen istekler 502 ile sonuçlanır.
Yanlış yapılandırılmış proxy ayarları da sıklıkla görülen bir nedendir. Nginx veya Apache’nin proxy direktiflerinde yanlış yazılmış bir IP adresi, hatalı bir port numarası ya da eksik bir upstream bloğu, sunucu yazılımı düzgün çalışsa bile 502 üretmeye yeter.
Ağ sorunları ve güvenlik duvarı kısıtlamaları, proxy ile upstream sunucu arasındaki bağlantıyı keserek aynı hataya yol açabilir. Özellikle bulut ortamlarında güvenlik grupları veya VPC yapılandırmaları yanlış ayarlandığında, iki sunucu birbirini göremez hale gelir.
Kaynak yetersizliği, yani bellek dolması veya CPU tükenmesi de upstream sunucunun yanıt üretememesine neden olur. Yüksek trafikli anlarda uygulama sunucusu yeni bağlantıları kabul edemeyecek hale gelir ve proxy sunucu geçersiz yanıt aldığını düşünerek 502 döndürür.
DNS çözümleme hataları, proxy sunucunun upstream sunucunun adresini bulamadığı durumlarda da 502 görülür. Bu durum genellikle alan adı değişikliklerinin ardından eski DNS önbelleklerinin temizlenmemiş olmasından kaynaklanır.
Sertifika sorunları ve SSL/TLS uyumsuzlukları, özellikle backend sunucularla HTTPS üzerinden konuşulduğunda 502’ye yol açabilir. Proxy, upstream sunucunun sertifikasını doğrulayamazsa bağlantıyı geçersiz sayar.
Son olarak üçüncü taraf servisler ve API bağımlılıkları da göz ardı edilmemelidir. Uygulamanız dışarıdan bir API’ye bağımlıysa ve o API yanıt vermiyorsa, kendi sunucunuz sağlıklı çalışıyor olsa bile 502 üretebilirsiniz.
Sunucu Tarafı Çözümleri
Bir web sitesi veya uygulama yöneticisiyseniz 502 hatasını çözmek için izlemeniz gereken sistematik bir yol haritası vardır.
Uygulama sunucusunun durumunu kontrol etmek ilk adım olmalıdır. systemctl status php-fpm, pm2 status veya supervisorctl status gibi komutlarla ilgili servisin çalışıp çalışmadığını doğrulayın. Servis durmuşsa yeniden başlatın ve başlatma hatalarını log dosyalarından inceleyin. /var/log/ altındaki uygulama logları çoğunlukla sorunun gerçek kaynağını açıkça gösterir.
Nginx veya Apache yapılandırmasını doğrulamak ikinci kritik adımdır. nginx -t komutu, yapılandırma dosyasındaki sözdizimi hatalarını anında ortaya koyar. Proxy bloğundaki proxy_pass direktifinin doğru IP ve port ile yazıldığından emin olun. Upstream sunucu adını IP yerine alan adıyla tanımladıysanız DNS çözümlemesini de test edin.
Zaman aşımı değerlerini optimize etmek, yüksek işlem süresi gerektiren uygulamalarda 502’yi önlemenin etkili bir yoludur. Nginx için proxy_read_timeout, proxy_connect_timeout ve proxy_send_timeout değerlerini uygulamanızın gerçek ihtiyaçlarına göre artırmak, geçici yavaşlamalarda 502 üretilmesinin önüne geçer.
proxy_read_timeout 300s;
proxy_connect_timeout 75s;
proxy_send_timeout 300s;Kaynak kullanımını izlemek ve sınırları genişletmek de önemli bir adımdır. top, htop veya vmstat araçlarıyla sunucunun anlık bellek ve CPU kullanımını gözlemleyin. PHP-FPM kullanıyorsanız pm.max_children değerinin mevcut trafik yüküne uygun şekilde ayarlandığından emin olun. Node.js uygulamalarında bellek sızıntılarını tespit etmek için --inspect bayrağı ve profiling araçlarından yararlanın.
SSL/TLS yapılandırmasını gözden geçirmek, backend HTTPS bağlantılarında 502 alıyorsanız atlanmaması gereken bir adımdır. Nginx’te proxy_ssl_verify off ayarını geçici olarak aktif ederek sorunun sertifika doğrulamasından kaynaklanıp kaynaklanmadığını test edebilirsiniz; ancak bu ayarı kalıcı olarak açık bırakmak güvenlik açığı oluşturur.
CDN ve WAF yapılandırmalarını incelemek de özellikle Cloudflare, Fastly veya benzeri bir servis kullanıyorsanız kritik önem taşır. CDN’nin kendi önbelleklenmiş bir 502 sayfası sunuyor olabileceğini ve gerçek sunucunuzun sağlıklı çalışıyor olabileceğini göz önünde bulundurun. CDN’yi geçici olarak devre dışı bırakarak sorunu izole edin.
İstemci Tarafı Çözümleri
Eğer 502 hatasıyla karşılaşan bir son kullanıcıysanız, sorunun büyük olasılıkla sunucu tarafında olduğunu bilmek başlı başına rahatlатıcıdır. Yine de tarayıcı veya ağ kaynaklı bazı durumlar bu hatayı tetikleyebilir.
Sayfayı yenilemek ve birkaç dakika beklemek, kulağa basit gelse de çoğu zaman işe yarar. Sunucu geçici bir yük artışı veya yeniden başlatma sürecindeyse kısa bir süre sonra normal işleyişine kavuşacaktır.
Tarayıcı önbelleğini ve çerezleri temizlemek, tarayıcının eski ve bozuk bir yanıtı önbellekten sunduğu durumlarda çözüm üretir. Chrome’da Ctrl + Shift + Del kısayoluyla önbellek temizleme ekranına erişebilirsiniz.
Farklı bir tarayıcı veya gizli mod denemek, sorunun tarayıcı uzantılarından ya da oturum çerezlerinden kaynaklanıp kaynaklanmadığını anlamanızı sağlar.
DNS önbelleğini temizlemek, özellikle yakın zamanda alan adı değişikliği yaşanan sitelerde etkili olabilir. Windows’ta ipconfig /flushdns, macOS’ta sudo dscacheutil -flushcache komutları bu işlemi gerçekleştirir.
VPN veya proxy yazılımını geçici olarak devre dışı bırakmak, ağ yönlendirmesini değiştiren bu araçların zaman zaman 502’ye zemin hazırlayabileceğini göz önünde bulundurarak uygulanması gereken bir adımdır.
502 Bad Gateway Hatası ile İlgili Sık Yapılan Hatalar
502 hatasıyla mücadelede hem yöneticilerin hem kullanıcıların düştüğü bazı yaygın tuzaklar bulunmaktadır.
Sorunu doğru katmanda aramamak, en temel hatadır. Nginx loglarına bakarken uygulama servisinin çökmüş olduğunu gözden kaçırmak ya da tam tersine saatler boyu uygulama loglarını incelerken sorunun aslında bir güvenlik duvarı kuralından kaynaklandığını fark edememek, troubleshooting sürecini gereksiz yere uzatır. Katmanlı ve sistematik bir yaklaşım her zaman en doğrusudur.
Zaman aşımı değerlerini gereğinden fazla artırmak, sorunu örtbas etmek anlamına gelir. Örneğin bir API çağrısı normalde 2 saniyede tamamlanıyorken 60 saniyeye uzaması, zaman aşımını 120 saniyeye çıkarmakla değil; ilgili servisin neden bu kadar yavaşladığını anlamakla çözülmelidir.
CDN önbelleğini ihmal etmek de sık rastlanan bir hatadır. Sunucu düzeltilmiş olsa bile CDN’nin eski bir 502 yanıtını önbellekte tutması, sorunu çözüldükten sonra da kullanıcılara göstermeye devam edebilir. CDN önbelleğini manuel olarak temizlemek (purge) bu senaryoda zorunludur.
İzleme ve uyarı sistemi kurmamak, 502 hatalarının reaktif değil proaktif bir şekilde yönetilmesini engelleyen yapısal bir eksikliktir. Uptime Robot, Pingdom veya Datadog gibi araçlarla hem dışarıdan hem içeriden izleme kurulması, sorunları kullanıcılar fark etmeden tespit etmenizi sağlar.
Logları düzenli arşivlememek veya log rotasyonu ayarlamamak da ciddi bir sorundur. Bir 502 dalgası yaşandıktan sonra sorunu analiz etmek için geriye dönük log verisi bulamıyorsanız aynı hatanın tekrar yaşanmasını engellemek güçleşir.
502 Bad Gateway hatası, ilk bakışta gizemli görünse de doğru araçlar ve sistematik bir yaklaşımla büyük ölçüde kontrol altına alınabilir. Sorunun kalıcı çözümü için iyi yapılandırılmış bir izleme altyapısı, anlamlı log kayıtları ve düzenli performans testleri üçlüsünü bir arada uygulamak, hem anlık krizleri hem de uzun vadeli istikrarsızlıkları önlemenin en güvenilir yoludur.
