CORS Hatası Nedir, Sunucu Tarafında Nasıl Çözülür?

---

Tarayıcı konsolunda "has been blocked by CORS policy" satırını gördüğünüzde ilk içgüdü genelde istemci tarafındaki kodu didiklemek olur. Oysa bu hata, tarayıcının kendi güvenlik kuralı gereği verdiği bir engelleme sinyalidir ve düzeltmesi neredeyse her zaman istek atılan sunucu tarafında yapılır; istemci kodunda deneyip durmak vakit kaybettirir.

Bu yazı, CORS hatasının neden istemci değil sunucu sorunu olduğunu, resmî Fetch standardına ve MDN'in teknik dokümantasyonuna dayanarak açıklıyor.

Tarayıcı bu isteği neden kendiliğinden engelliyor?​

MDN'in CORS belgesine göre tarayıcılar, `fetch()` veya `XMLHttpRequest` gibi API'lerle başlatılan betik kaynaklı istekleri güvenlik gerekçesiyle kısıtlıyor ve aynı köken (same-origin) politikasını uyguluyor. Bu, bir web uygulamasının yalnızca kendi yüklendiği kökenden kaynak isteyebileceği, farklı bir kökenden gelen yanıtın ancak doğru CORS başlıklarını taşıması durumunda kabul edileceği anlamına geliyor.

Belge ayrıca hata hakkında ayrıntıların JavaScript koduna kasıtlı olarak açılmadığını belirtiyor: kod yalnızca bir hata oluştuğunu bilir, nedenini konsoldaki mesajdan okumanız gerekir. Bu tasarım tercihi bilinçli bir güvenlik kararı; istemci tarafında bu davranışı "atlatacak" bir çözüm de bulunmuyor.

Belgeye göre bazı istekler önce bir "preflight" (ön uçuş) isteğiyle denetleniyor; tarayıcı asıl isteği göndermeden önce sunucuya OPTIONS metoduyla bir kontrol isteği atıp sunucunun asıl isteğe izin verip vermeyeceğini önceden öğreniyor. Bu ön kontrol, isteğin metodu GET/POST/HEAD dışında bir şeyse (PUT, DELETE gibi) ya da istek özel başlıklar taşıyorsa devreye giriyor; sunucu bu OPTIONS isteğine doğru izin başlıklarıyla yanıt vermezse asıl istek hiç gönderilmiyor.

Kimlik bilgisi (credential, örneğin çerez) taşıyan isteklerde bu denetim daha da katı: MDN'in belirttiğine göre böyle bir istek için gereken izin başlığı yanıtta yoksa, tarayıcı bu yanıtı basit bir GET isteği olsa bile web içeriğine hiç döndürmüyor, sessizce yok sayıyor.

İzni gerçekte kim veriyor?​

WHATWG'nin Fetch standardı, CORS protokolünün sunucunun döndürdüğü yanıt başlıkları üzerinden işlediğini tanımlıyor; örneğin `Access-Control-Expose-Headers` başlığı, tarayıcının hangi yanıt başlıklarını istemci koduna göstereceğini sunucunun kendisinin belirlemesini sağlıyor. Yani izni veren taraf istemci değil, isteği karşılayan sunucudur; tarayıcı sadece bu izni denetleyip uyguluyor.

Bu da hatanın çözümünün neden neredeyse hep sunucu tarafında olduğunu açıklıyor: sunucu doğru `Access-Control-Allow-Origin` başlığını (ve gerekiyorsa kimlik bilgisi izinlerini) döndürmüyorsa, istemci ne yaparsa yapsın tarayıcı yanıtı engellemeye devam eder.

Fetch standardı ayrıca yanıtın hangi başlıklarının istemci koduna görünür olacağını da "CORS-safelisted" adında sabit bir liste üzerinden belirliyor; `Cache-Control`, `Content-Language`, `Content-Length`, `Content-Type`, `Expires`, `Last-Modified` ve `Pragma` gibi başlıklar varsayılan olarak görünürken, isteğin geri kalanı engellenmese bile özel bir başlık (ör. kendi API'nizin eklediği bir sayfalama başlığı) sunucu bunu `Access-Control-Expose-Headers` ile açıkça belirtmedikçe istemci kodunda görünmez. Bazen "CORS hatası almıyorum ama başlığı okuyamıyorum" şikâyetinin kaynağı da tam olarak bu.

Ön uçtan geçici çözüm aramanın neden işe yaramadığı​

Bazı geliştiriciler CORS hatasını bir tarayıcı uzantısıyla ya da tarayıcının güvenlik ayarını geçici olarak kapatarak "atlatmaya" çalışır; bu, geliştirme ortamında kendi makinenizde geçici olarak işe yarasa da üretim ortamında gerçek kullanıcılar için bir çözüm değildir, çünkü kullanıcının tarayıcısında böyle bir ayar ya da uzantı olmayacaktır. Kalıcı çözüm, isteğin gittiği API'yi kendi sunucunuzda çalıştırıyorsanız doğru CORS başlıklarını eklemek; üçüncü taraf bir API'yse o API sağlayıcısının CORS ayarlarını kontrol etmek ya da isteği kendi sunucunuz üzerinden vekil (proxy) olarak geçirmektir.

API'lerle ilk kez çalışıyorsanız web servislerinin genel mantığını başlıca web servisleri yazımızda, bir entegrasyonu adım adım kurmayı ise API entegrasyonları nasıl yapılır yazımızda ele almıştık.

CORS hatası almadan önce API yanıtını doğru okumak​

CORS engeli hiç yaşamadan da bir API'den beklenmedik sonuçlar alabilirsiniz; sayfalama parametreleri yanlış kurulduğunda kayıtların eksik gelmesi ya da tekrarlanması bunlardan biri, bunu API sayfalamasında kayıtlar neden eksilir veya tekrarlanır yazımızda ayrı olarak ele almıştık; CORS ile karıştırılmaması gereken, ayrı bir teşhis konusu. İki hatanın da ortak noktası, sorunun genelde istemci kodunda değil isteğin gittiği veya karşıladığı sunucu tarafında aranması gerektiği.

Sık Sorulan Sorular​

CORS hatası nedir?
Tarayıcının, farklı bir kökenden (origin) gelen bir kaynağı, o kaynağı sunan sunucu doğru izin başlıklarını döndürmediği için engellemesi sonucu oluşan bir güvenlik hatasıdır.

CORS hatası neden olur?
İstek atılan sunucu, isteği yapan kökene izin veren `Access-Control-Allow-Origin` gibi başlıkları yanıtına eklemediğinde, tarayıcı yanıtı istemci koduna teslim etmeden engeller.

CORS hatası nasıl düzeltilir?
İstek gittiğiniz API kendi sunucunuzdaysa doğru CORS başlıklarını sunucu tarafında eklemeniz gerekir; üçüncü taraf bir API'yse sağlayıcının CORS ayarını kontrol etmek ya da isteği kendi sunucunuz üzerinden vekil olarak geçirmek gerekir.

Özetle​

CORS hatası tarayıcının kasıtlı bir güvenlik engellemesidir ve izni veren taraf her zaman istek atılan sunucudur; bu yüzden çözüm de istemci kodunda değil sunucunun döndürdüğü başlıklarda aranır. Üçüncü taraf bir API'yle çalışıyorsanız CORS ayarını değiştirme yetkiniz olmayabilir, bu durumda kendi sunucunuz üzerinden bir vekil katman kurmak pratik çözüm oluyor.

Aldığınız son CORS hatasında sorunun kaynağı kendi sunucunuz muydu, yoksa üçüncü taraf bir API mi, yoksa başlık görünürlüğü gibi farklı bir ayrıntı mıydı?

Güncelleme: 25 Ağustos 2026.

---