Tutorial

CORS Hatası Nasıl Çözülür? Preflight ve Credentials Rehberi

Mehmet Fatih Ünal
31 Ekim 2026
6 dk okuma
#CORS#HTTP#Fetch API#Frontend#API#Web Güvenliği
CORS Hatası Nasıl Çözülür? Preflight ve Credentials Rehberi

CORS hatası ne anlama gelir?

CORS, bir sunucunun hangi origin üzerinden çalışan tarayıcı koduyla yanıt paylaşacağını belirleyen HTTP mekanizmasıdır. API'nin yanıt vermesi ile JavaScript'in bu yanıtı okuyabilmesi farklı aşamalardır. Konsoldaki CORS mesajını çözmek için önce engelin preflight sırasında mı, asıl yanıt okunurken mi oluştuğunu belirleyin. MDN CORS rehberi bu alışverişin temelini açıklar.

Bir komut satırı istemcisinin aynı adresten veri alması, tarayıcının da alacağını kanıtlamaz. Komut satırı araçları tarayıcıdaki aynı origin denetimini uygulamaz. Sorunu yalnızca API'nin durum koduna bakarak değerlendirmek bu yüzden eksik kalır.

Aynı alan adı neden her zaman aynı origin değildir?

Origin; şema, host ve port birleşimidir. https://app.example.com ile https://api.example.com farklı origin değerleridir. localhost üzerinde iki farklı port da aynı duruma yol açar. Buna karşılık aynı origin altındaki /profile ve /orders yolları, yalnızca yolları farklı diye CORS gerektirmez. Tanım için same-origin policy belgesine bakabilirsiniz.

İlk teşhiste tarayıcının gönderdiği Origin değerini kaydedin. Bir izin listesine URL'nin yolunu eklemek veya üretimdeki origin yerine geliştirme adresini bırakmak beklenen eşleşmeyi sağlamaz.

OPTIONS preflight ne zaman gönderilir?

Tarayıcı bazı cross-origin isteklerden önce OPTIONS ile izin kontrolü yapar. Örneğin Content-Type değeri application/json olan bir POST bu kontrolü gerektirir. Her GET isteğinin preflight oluşturduğunu varsaymayın; yöntemle birlikte başlıklar da önemlidir. Bu ayrım Fetch Standardı'nın CORS kurallarında tanımlanır.

Aşağıdaki örnek, https://app.example.com üzerinde çalışan bir sayfanın JSON önizleme isteğidir. Adresler temsili; endpoint'in uygulaması örneğe dahil değildir.

const response = await fetch('https://api.example.com/preview', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ title: 'Taslak' }),
});

if (!response.ok) {
  throw new Error('Preview request failed');
}

const preview = await response.json();

Tarayıcının ürettiği ön kontrolün ilgili satırları şöyledir:

OPTIONS /preview HTTP/1.1
Host: api.example.com
Origin: https://app.example.com
Access-Control-Request-Method: POST
Access-Control-Request-Headers: content-type

OPTIONS isteğini uygulama kodundan ayrıca göndermeniz gerekmez. Ön kontrol başarısızsa tarayıcı asıl POST isteğini göndermez. Preflight açıklaması, bu isteğin tarayıcı tarafından üretildiğini gösterir. Ağ panelinde sadece OPTIONS görmek, endpoint'in POST koduna henüz ulaşılmadığı anlamına gelebilir.

Çerezli istekte sunucu hangi başlıkları döndürmeli?

Sunucu bu origin, yöntem ve başlığa izin veriyorsa örnekteki preflight için şu yanıtı verebilir:

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: POST
Access-Control-Allow-Headers: Content-Type
Access-Control-Allow-Credentials: true
Vary: Origin

Asıl POST yanıtında da Access-Control-Allow-Origin ve Access-Control-Allow-Credentials bulunmalıdır. İzin listesinden seçilen origin'e göre yanıt değişiyorsa Vary: Origin değerini de koruyun. Yalnızca OPTIONS yanıtını düzeltmek yeterli değildir.

credentials: 'include' kullanılan bir istekte Allow-Origin değeri yıldız olamaz; açık origin gerekir. Birden çok origin'i virgülle aynı başlığa yazmak da çözüm değildir. Sunucu gelen origin'i izin listesinde doğrulayıp uygun tek değeri döndürmelidir. Allow-Origin belgesi bu eşleşmeyi açıklar.

Preflight normalde çerez taşımaz. Bu nedenle OPTIONS aşamasında kullanıcı oturumu zorunlu tutmak izin kontrolünü engelleyebilir. Bu durum, asıl endpoint'in kimlik doğrulamasını kaldırmak için gerekçe değildir. Allow-Credentials belgesi iki aşamayı ayrı ele alır.

no-cors veya yıldız kullanmak sorunu çözer mi?

no-cors, JSON yanıtını okunabilir hale getirmez. Ortaya çıkan opaque yanıtın gövdesi ve başlıkları JavaScript'e açılmaz; durum kodu 0 görünür. Çerezin SameSite niteliği ve tarayıcının üçüncü taraf çerez politikası da credentials: 'include' ile geçersiz kılınmaz. Ayrıntılar Fetch kullanım rehberindedir.

CORS'u kimlik doğrulama veya bütün istekleri engelleyen bir güvenlik duvarı olarak düşünmeyin. Preflight gerektirmeyen bir istek sunucuya ulaşmış olsa bile yanıtı tarayıcı koduna açılmayabilir. Durum değiştiren işlemler için yetkilendirme ve uygun CSRF korumasını ayrıca tasarlayın.

Ağ panelinde hangi sırayla kontrol yapılmalı?

  1. Sayfanın origin değerini, hedef URL'yi ve gerçek istek yöntemini karşılaştırın.
  2. OPTIONS varsa istenen yöntem ve başlıklarla sunucunun izinlerini eşleştirin.
  3. POST veya GET gönderildiyse onun yanıtındaki CORS başlıklarını da inceleyin. Hata yanıtlarını atlamayın.
  4. Uygulama ve proxy'nin aynı başlığı iki kez ekleyip eklemediğini kontrol edin.
  5. İzin verilen ve verilmeyen iki origin ile tarayıcı testi yapın; yalnızca başarılı senaryoyla yetinmeyin.

Dinamik origin yanıtlarında Vary başlığının önbellekle ilişkisini de düşünün. HTTP önbellekleme rehberi bu tarafı, API retry yazısı ise başarısız görünen bir isteği tekrar gönderirken dikkat edilecek noktaları tamamlar.

Sık sorulan sorular

API 200 dönüyorsa CORS neden hata verir? Sunucu yanıtı üretmiş olabilir; tarayıcı, başlıklara göre bu yanıtı JavaScript ile paylaşmayı yine de reddedebilir.

Preflight olmaması CORS kontrolü olmadığı anlamına mı gelir? Hayır. Asıl yanıtın paylaşım izni yine değerlendirilir.

Allow-Origin başlığını fetch isteğine eklemek işe yarar mı? Hayır. Bu izin sunucunun yanıtında bulunmalıdır.

CORS hatasında POST kesinlikle çalışmamış mıdır? Hayır. Ön kontrolün başarısız olması ile gönderilmiş bir POST yanıtının engellenmesi farklıdır. İşlemi tekrarlamadan önce hangi aşamanın başarısız olduğunu bulun.

Daha Fazla İçerik

Blog sayfasında diğer yazılarımı keşfedin

Tüm Yazılar