REST API İsteklerinde 401 ve 403 Hatalarını Teşhis Etme

REST API hata teşhisi sırasında 401 ve 403 yanıtlarını ayırmanın en pratik yolu, sunucunun kimlik doğrulama bilgisini değerlendirme aşamasına mı yoksa erişim izni aşamasına mı takıldığını incelemektir. 401 çoğunlukla sunucunun istekteki kimlik doğrulama bilgisini kabul edemediğini veya geçerli bir kimlik doğrulama bağlamı oluşturamadığını düşündürür; 403 ise kimlik bilgisi değerlendirilmiş olsa bile istenen kaynak ya da işlem için yeterli izin bulunmadığına işaret eder.

Ancak bu ayrım mutlak ve tek nedenli bir kural değildir. API’nin tasarımı, aradaki güvenlik katmanı, gateway davranışı ve bilgi maskeleme tercihleri aynı durumu farklı kodlarla gösterebilir. Bu nedenle doğru teşhis, yalnızca durum kodunu okumakla değil, gönderilen gerçek isteği, yanıt başlıklarını, token özelliklerini ve sunucu loglarını birlikte karşılaştırmakla yapılır.

401 ve 403 Hataları Arasındaki Temel Fark Nedir?

Günlük hayattan bir benzetmeyle düşünürsek kimlik doğrulama, bir binanın girişinde “Sen kimsin?” sorusuna cevap vermektir. Yetkilendirme ise “Kimliğin doğrulandı; peki bu odaya girmene izin var mı?” sorusudur. API tarafında authentication kullanıcının, uygulamanın veya servisin kimliğini doğrulamaya; authorization ise doğrulanan kimliğin belirli bir kaynak veya işlem üzerindeki izinlerini kontrol etmeye karşılık gelir.

Örneğin istemci, korumalı bir sipariş endpoint’ine şu tür bir istek gönderebilir:

GET /api/orders/1842
Authorization: Bearer eyJhbGciOi...

Sunucu token’ı okuyamıyor, token geçersiz görünüyor veya gerekli kimlik doğrulama bilgisi isteğe hiç ulaşmıyorsa ilk şüphe 401 olur. Token okunabilir ve bir kullanıcıya ya da servise bağlanabilir durumda olduğu hâlde bu kimliğin 1842 numaralı siparişi görme yetkisi yoksa 403 olasılığı güçlenir.

HTTP standardında 401, hedef kaynağa erişim için geçerli kimlik doğrulama bilgilerinin eksik veya geçersiz olduğu durumlarla ilişkilendirilir. 403 ise sunucunun isteği anladığını fakat isteği yerine getirmeyi reddettiğini ifade eder. Bununla birlikte 403 yanıtı, her zaman yalnızca kullanıcı rolünün eksik olduğu anlamına gelmez; kaynak politikası, işlem kısıtı veya güvenlik tasarımı da etkili olabilir. Ayrıntılı standart açıklaması için RFC 9110 HTTP Semantics incelenebilir.

401 yanıtı her zaman token süresinin dolduğu anlamına mı gelir?

Hayır. Token süresinin dolması 401 için yaygın bir olasılık olsa da tek açıklama değildir. Token’ın bozulmuş olması, imzasının doğrulanamaması, yanlış bir kimlik doğrulama şeması kullanılması, Authorization başlığının proxy veya istemci katmanında kaybolması, yanlış issuer ya da audience değeri ve token’ın iptal edilmiş olması da benzer sonuca yol açabilir.

Örneğin şu iki başlık görünüşte benzer olsa da sunucu açısından farklıdır:

Authorization: Bearer eyJhbGciOi...
Authorization: BearereyJhbGciOi...

İkinci satırda Bearer ile token arasında boşluk yoktur. Bu nedenle token değeri doğru olsa bile sunucu beklediği kimlik doğrulama biçimini algılayamayabilir. Benzer şekilde başlık adının yanlış yazılması, token’ın boş bir değişkenden gelmesi veya istemcinin eski bir ortam değişkenini kullanması da 401 teşhisinde kontrol edilmelidir.

OAuth 2.0 Bearer Token kullanımında geçersiz, bozuk, süresi dolmuş veya başka bir nedenle doğrulanamayan access token için 401 kullanımı yaygın biçimde tanımlanır. Fakat gerçek uygulamada hangi koşulun 401, hangisinin farklı bir hata kodu olarak döneceğini ilgili API’nin dokümantasyonu ve logları belirler. Bu ayrım için RFC 6750 Bearer Token Usage içindeki hata açıklamalarına bakılabilir.

403 yanıtı her zaman rol eksikliğini mi gösterir?

Hayır. “403 aldıysam kullanıcıya admin rolü verilmemiştir” şeklindeki yaklaşım fazla dar bir genellemedir. Kullanıcı rolü yeterli görünse bile şu koşullar erişimi engelleyebilir:

• Token içinde endpoint’in beklediği scope bulunmuyor olabilir.
• Kullanıcı doğru rolde olsa bile belirli kaynağın sahibi olmayabilir.
• GET işlemine izin verilirken PUT veya DELETE işlemine izin verilmiyor olabilir.
• İstek doğru kullanıcıyla yapılmış olsa bile doğru tenant, proje veya organizasyon bağlamına ait olmayabilir.
• Kaynak durumu, iş kuralı veya hesap durumu işlemi kısıtlıyor olabilir.
• Güvenlik katmanı, gerçek nedeni dışarıya açıklamamak için genel bir 403 döndürüyor olabilir.

Örneğin bir kullanıcı kendi profilini okuyabilirken başka bir kullanıcının profilini güncellemeye çalıştığında 403 alabilir. Burada sorun token’ın geçersiz olması değil, doğrulanmış kimliğin hedef kaynak ve seçilen HTTP metodu için yeterli yetkiye sahip olmamasıdır.

API neden beklenenden farklı bir durum kodu döndürebilir?

Bir REST API’nin önünde reverse proxy, API gateway, web application firewall veya ayrı bir kimlik doğrulama servisi bulunabilir. İsteği asıl uygulama yerine bu katmanlardan biri reddediyorsa dönen kod, uygulamanın kendi hata eşlemesiyle aynı olmayabilir. Ayrıca bazı sistemler kaynak hakkında bilgi sızdırmamak için yetkisiz bir isteği 403 yerine 404 ile maskeleyebilir.

Bu yüzden durum kodunu “kesin karar” değil, ilk teşhis ipucu olarak ele almak gerekir. 401 gördüğünüzde önce kimlik doğrulama zincirini; 403 gördüğünüzde ise kimlik doğrulama başarılı kabul edilse bile kaynak ve işlem izinlerini inceleyin. Fakat iki durumda da gerçek isteğin URL’sini, metodunu, başlıklarını ve sunucu logunu karşılaştırmadan sonuca atlamayın.

Gerçek İsteği Önce Postman'da ve İstemci Kodunda İnceleyin

401 veya 403 teşhisinde sık yapılan hata, yalnızca ekranda görünen endpoint adresine bakmaktır. Oysa sunucuya ulaşan istek; URL, path değişkenleri, sorgu parametreleri, HTTP metodu, başlıklar, gövde, yönlendirmeler ve ortam değişkenlerinin birleşiminden oluşur. Postman’da doğru görünen bir istek ile Python veya Java istemcisinin ürettiği istek arasında tek bir Authorization başlığı farkı bile sonucu değiştirebilir.

Postman, gönderilen istek ve alınan yanıtla ilgili ayrıntıları Console üzerinden incelemeye izin verir. Arayüzdeki menü ve düğme adları sürüme veya masaüstü/web kullanımına göre değişebileceği için güncel görünümde footer bölümündeki Console seçeneğini veya ilgili istek ayrıntılarını esas alın. Postman API isteklerini hata ayıklama dokümantasyonu gerçek gönderilen başlıkları, değişken değerlerini, yönlendirmeleri ve ham yanıtı inceleme yaklaşımını açıklar.

İstek karşılaştırmasında izlenecek sıra

Postman isteği ile Python isteğini nasıl karşılaştırabilirsiniz?

Postman’da isteği gönderdikten sonra Console kaydında görünen URL, metod ve başlıkları not edin. Hassas token değerini kopyalamak veya paylaşmak yerine token’ın gönderilip gönderilmediğini, başındaki şemanın doğru olup olmadığını ve mümkünse token’ın güvenli biçimde maskelenmiş uzunluğunu kontrol edin.

Python tarafında özellikle şu yapı incelenmelidir:

headers = {
    "Accept": "application/json",
    "Authorization": f"Bearer {token}",
}
response = requests.get(
    "https://api.example.test/orders/1842",
    headers=headers,
    timeout=10,
)

Burada token değişkeninin boş olup olmadığı, başında veya sonunda görünmeyen boşluk bulunup bulunmadığı ve kullanılan URL’nin Postman’daki URL ile aynı olup olmadığı kontrol edilir. Gerçek token değerini terminale, issue kaydına veya ekip sohbetine yazdırmak yerine yalnızca şu tür güvenli bir gözlem alınabilir:

print("token var mı:", bool(token))
print("token uzunluğu:", len(token) if token else 0)
print("url:", response.request.url)
print("method:", response.request.method)
print("authorization gönderildi:",
      "Authorization" in response.request.headers)

Bu çıktı, token’ın içeriğini ifşa etmeden istemcinin gerçekten hangi isteği oluşturduğunu gösterir. Java istemcisinde de benzer biçimde, HTTP request builder’a eklenen başlıklar, environment değişkenlerinden okunan base URL ve olası redirect davranışı incelenmelidir. Yalnızca kaynak kodda Authorization satırının bulunması yeterli değildir; önemli olan başlığın son ağ isteğinde gerçekten yer almasıdır.

Postman ve istemci aynı isteği göndermiyorsa ne anlaşılır?

Postman başarılı, istemci 401 döndürüyorsa ilk şüphe istemci tarafındaki başlık, token kaynağı, URL veya ortam farkıdır. Postman da 401 döndürüyorsa kimlik doğrulama bilgilerinin kendisi, token’ın hedef API için üretilip üretilmediği veya sunucudaki doğrulama yapılandırması incelenmelidir.

Postman ve istemci aynı token ile 403 döndürüyor fakat farklı kaynaklarda farklı sonuç alıyorsa, sorun büyük olasılıkla kaynak kimliği, HTTP metodu veya izin modelinin ayrıntılarındadır. Bir istemcinin “çalışıyor” görünmesi, diğer istemcinin de aynı isteği ürettiğini kanıtlamaz; iki isteği satır satır karşılaştırmak gerekir.

401 ve 403 İçin Sıralı API Hata Teşhis Kontrol Listesi

Aşağıdaki akış, durum kodunu tahmin etmeye değil, her aşamada gözlenebilir bir kanıt toplamaya dayanır. Bir adımda beklenen gözlem elde edilemiyorsa sonraki adıma geçmeden o farkı düzeltin. Temel seviyenizi ölçmek isterseniz, HTTP istekleri ve koşullu düşünme için ücretsiz kodlama bilgisi testi üzerinden mevcut altyapınızı da kontrol edebilirsiniz.

Token alanlarını kontrol ederken nelere dikkat edilmeli?

Token süresi, scope, role, audience ve issuer alanlarının adı, veri tipi ve değerlendirme yöntemi kullanılan kimlik doğrulama altyapısına göre değişebilir. Bu alanları evrensel bir şema gibi ele almayın. Bir sistem scope kullanırken başka bir sistem izinleri farklı claim’lerde taşıyabilir; bir API rolü doğrudan token’dan okumak yerine kullanıcı ve kaynak ilişkisini sunucu tarafında sorgulayabilir.

Bu nedenle token içindeki bir claim’i görmek tek başına erişim garantisi vermez. Örneğin token’da admin benzeri bir rol bulunsa bile endpoint, belirli bir tenant’a ait kaynağa erişim veya yalnızca belirli HTTP metodları için ayrıca izin isteyebilir. Teşhis sırasında şu soruları sırayla sorun:

•  
• Bu token hangi kullanıcı veya servis adına üretildi?
•  
• Token hangi API ya da audience için geçerli?
•  
• Token’ın süresi ve imza doğrulaması başarılı mı?
•  
• İstenen işlem için gerekli scope veya izin mevcut mu?
•  
• Bu kimlik, hedef kaynağın sahibi ya da yetkili tüketicisi mi?
•  
• Gateway ve uygulama aynı izin modelini mi uyguluyor?
•  

401 alındığında listenin 3, 4 ve 5. adımları; 403 alındığında ise özellikle 6, 7 ve 8. adımları öne alınabilir. Yine de bu bir kestirme kuraldır, kesin teşhis değildir. Örneğin eksik Authorization başlığı bazı güvenlik katmanlarında 403 olarak maskelenebilir; bu yüzden her iki kodda da başlığın gerçekten gönderildiğini doğrulamak güvenli başlangıçtır.

Kontrol listesini ne zaman durdurmalısınız?

Bir adımda beklenen gözlem yoksa hatayı “muhtemelen rol sorunu” diyerek sonraki katmana taşımayın. URL yanlışsa token’ı değiştirmek, token biçimi bozuksa kullanıcı rolünü güncellemek veya log görülmeden istemciyi yeniden yazmak teşhisi zorlaştırır. Her düzeltmeden sonra aynı URL, metod ve kontrollü kimlik bilgileriyle tek bir tekrar isteği gönderin; böylece hangi değişikliğin sonucu etkilediğini ayırt edebilirsiniz.

Küçük Karar Ağacıyla 401 mi 403 mü Olduğunu Ayırın

401 ve 403 hatalarını ayırırken tek bir hata mesajına bakarak kesin sonuca varmak yerine, aynı isteğin kontrollü varyasyonlarını karşılaştırın. İlk soru, sunucunun gerçekten 401 mi yoksa 403 mü döndürdüğüdür; sonraki adımlar ise kimlik doğrulama bilgisinin ve kullanıcının izinlerinin sonucu nasıl değiştirdiğini gösterir. HTTP semantiğinde 401, hedef kaynak için geçerli kimlik doğrulama bilgilerinin bulunmadığını veya sunucu tarafından kabul edilmediğini; 403 ise sunucunun isteği anlayıp mevcut kimlik bilgilerini erişim için yetersiz bulduğunu ifade edebilir. Ancak uygulamaların yanıt gövdeleri ve hata alanları aynı olmak zorunda değildir. ([rfc-editor.org](https://www.rfc-editor.org/rfc/rfc9110.pdf?utm_source=openai))

Bu nedenle aşağıdaki akışı kesin teşhis kuralı olarak değil, hipotez daraltma yöntemi olarak kullanın. URL, HTTP metodu ve istek gövdesi sabit kalmalı; her denemede yalnızca kimlik doğrulama bilgisi veya kullanıcı rolü değiştirilmelidir. Böylece ortaya çıkan farkın token’dan mı, rolden mi, istemci yapılandırmasından mı yoksa sunucu tarafındaki başka bir politikadan mı kaynaklandığını daha güvenilir biçimde izleyebilirsiniz.

Adım 1: Sunucu hangi HTTP durum kodunu döndürüyor?

•  
• 401 görüyorsanız ilk hipotez kimlik doğrulama katmanında sorun olduğudur. Token eksik, bozuk, süresi dolmuş, yanlış biçimde gönderilmiş veya sunucu tarafından kabul edilmeyen bir kimlik doğrulama yöntemi kullanılmış olabilir.
•  
• 403 görüyorsanız kimlik doğrulama sunucu tarafından tanınmış olabilir; fakat kullanıcı, rol, kapsam, kaynak politikası veya işlem izni bakımından yetersiz kabul ediliyor olabilir.
•  
• 401 veya 403 dışındaki bir kod görüyorsanız akışı zorla bu iki kategoriye sokmayın. URL, metot, istek gövdesi, içerik türü, yönlendirme, ağ geçidi ve sunucu tarafındaki başka kontrolleri ayrıca inceleyin.
•  

Durum kodunu Postman’daki yanıt bölümünden, istemci kodundaki status_code veya eşdeğer alanından ve mümkünse ağ izleme aracından doğrulayın. Sadece uygulamanın ekranda gösterdiği “istek başarısız” mesajına güvenmeyin; gerçek HTTP yanıtı farklı ayrıntılar içerebilir.

Adım 2: Authorization başlığı gerçekten gönderiliyor mu?

İstemci yapılandırmasında token değişkeninin dolu olması, başlığın gerçekten ağ üzerinden gönderildiğini garanti etmez. Postman’da Authorization sekmesinin isteğe uygulanıp uygulanmadığını, ön tanımlı değişkenlerin çözümlenip çözülmediğini ve hazırlanan gerçek isteğin Headers bölümünü kontrol edin. Kod tarafında ise ortak bir istemci katmanı başlığı silebilir, üzerine yazabilir veya farklı bir istek için kullanılan oturum ayarını değiştirebilir.

Başlık çoğunlukla şu yapıya benzer:

Authorization: Bearer <token>

Buradaki boşluk, Bearer ifadesinin yazımı ve token’ın başına veya sonuna yanlışlıkla eklenen tırnak işaretleri önemlidir. Token’ın tamamını loglamak yerine yalnızca güvenli bir özet, uzunluk veya ilk birkaç karakteri maskeleyerek kaydedin. Örneğin Bearer eyJ... gibi kısmi bir değer, “başlık gönderildi mi?” sorusunu incelemeye yardımcı olabilir; fakat gerçek erişim bilgisini açığa çıkarmamalıdır.

Adım 3: Authorization başlığını kaldırınca sonuç değişiyor mu?

Aynı URL, metot ve istek gövdesiyle iki kontrollü istek gönderin:

1.  
2. Geçerli olduğunu düşündüğünüz Authorization başlığıyla isteği gönderin.
3.  
4. Authorization başlığını tamamen kaldırarak aynı isteği yeniden gönderin.
5.  

İlk isteğin sonucu 200 iken başlık kaldırıldığında 401 oluyorsa, başlığın kimlik doğrulama akışında etkili olduğu düşünülebilir. Bu gözlem, token’ın kesin olarak doğru olduğunu kanıtlamaz; yalnızca sunucunun başlıksız isteği farklı bir kimlik doğrulama katmanında değerlendirdiğini gösterir.

İki isteğin de 401 dönmesi, başlığın hiç gönderilmediğini, biçimin hatalı olduğunu, token’ın kabul edilmediğini veya test edilen kaynağın başka bir kimlik doğrulama mekanizması beklediğini düşündürebilir. İki isteğin de 403 dönmesi ise uygulamanın başlıksız isteği bile aynı yetki politikasına yönlendirmesi, kaynak varlığını gizleme yaklaşımı veya ara katmandaki özel bir davranışla ilişkili olabilir. Bu noktada yalnızca durum koduna değil, yanıt başlıklarına, yanıt gövdesine ve sunucu loguna bakın.

Adım 4: Token yenilendiğinde veya geçerliliği doğrulandığında sonuç değişiyor mu?

Authorization başlığı gönderiliyor olsa bile token’ın geçerliliği ayrı bir sorudur. Token yenileme işlemi yaptıktan sonra aynı isteği, URL ve metodu değiştirmeden tekrar çalıştırın. Kimlik doğrulama sunucusunun veya uygulamanın dokümantasyonunda token’ın hangi kullanıcıyı, hangi kapsamları ve hangi geçerlilik bilgisini taşıdığı açıklanıyor olabilir.

•  
• Eski token 401, yeni token başarılı sonuç veriyorsa süre, iptal edilme veya token üretim süreci incelenmelidir.
•  
• Yeni token da 401 veriyorsa imza doğrulaması, beklenen kimlik doğrulama şeması, hedef ortam ve başlık biçimi kontrol edilmelidir.
•  
• Token yenilendiği hâlde 403 devam ediyorsa sorun büyük olasılıkla yalnızca token’ın geçerliliğiyle açıklanamaz; rol, kapsam veya kaynak politikası incelenmelidir.
•  

Bu çıkarımlar olasılık belirtir, kesin hüküm vermez. Bazı sistemler token geçersizliğini 401 yerine farklı bir uygulama hatasıyla gösterebilir veya güvenlik politikası nedeniyle ayrıntılı hata açıklaması vermeyebilir.

Adım 5: Aynı isteği farklı rol veya izinlere sahip kullanıcıyla deneyin

Üçüncü kontrollü varyasyonda yalnızca kullanıcıyı değiştirin. URL, HTTP metodu, istek gövdesi, istemci ve mümkün olduğunca token üretim yöntemi sabit tutulmalıdır. Kullanıcı A ile alınan sonuç ile Kullanıcı B’nin sonucu karşılaştırılırken iki hesabın gerçekten farklı rol veya izinlere sahip olduğu sunucu tarafında doğrulanmalıdır.

Örneğin A varyasyonunda yönetici rolüne sahip kullanıcı başarılı, C varyasyonunda yalnızca okuma izni bulunan kullanıcı 403 alıyorsa, ilk hipotez yetkilendirme katmanına kayar. Fakat bunu doğrulamak için sunucu logunda hangi kuralın isteği reddettiğini, token içindeki kapsamların nasıl yorumlandığını ve ilgili endpoint’in hangi izni beklediğini incelemek gerekir.

Adım 6: Yanıt gövdesi ve sunucu logu hangi katmanı işaret ediyor?

Yanıt gövdesinde error, code, message, scope veya benzeri alanlar bulunabilir; fakat alan adları ve mesajlar API sağlayıcısına ya da uygulamanın kendi hata modeline göre değişir. Belirli bir mesajı evrensel 401 veya 403 açıklaması gibi kabul etmeyin. HTTP standardı, 401 yanıtında kimlik doğrulama meydan okuması taşıyan WWW-Authenticate başlığını öngörür; 403 yanıtında ise sunucu gerekçeyi yanıt içeriğinde açıklayabilir, ancak ayrıntı sunmak zorunda değildir. ([rfc-editor.org](https://www.rfc-editor.org/in-notes/rfc9110.pdf?utm_source=openai))

Sunucu logunda şu sırayı arayın:

•  
• İsteğin zaman damgası ve mümkünse correlation ID değeri.
•  
• Çözümlenen URL, HTTP metodu ve hedef servis.
•  
• Kimlik doğrulama katmanının token’ı kabul edip etmediği.
•  
• Token’dan çıkarılan kullanıcı kimliği, rol veya kapsam bilgisi.
•  
• Yetkilendirme kararının hangi kural veya politika sonucunda verildiği.
•  
• Yanıtın hangi ara katman, gateway veya uygulama bileşeni tarafından üretildiği.
•  

İyi bir teşhis notu, varsayımı ve gözlemi birbirinden ayırır. Aşağıdaki şablonu her kontrollü istek için ayrı satırda doldurun:

İstek zamanı | URL/metot | kullanıcı | başlık durumu | yanıt kodu | yanıt gövdesi | log bulgusu
2026-08-29 14:10 | /resource GET | kullanıcı-A | gönderildi | 200 | beklenen veri | auth kabul, izin verildi
2026-08-29 14:12 | /resource GET | kullanıcı-A | kaldırıldı | 401 | uygulama hata alanı | credential yok
2026-08-29 14:14 | /resource GET | kullanıcı-B | gönderildi | 403 | uygulama hata alanı | rol politikası reddetti

Bu tablo üç varyasyon arasındaki farkı görünür hâle getirir. Fark yoksa istemci değişkeninin gerçekten uygulanıp uygulanmadığını kontrol edin; fark varsa değişen tek unsurun gerçekten başlık veya kullanıcı olduğundan emin olun.

Python requests ile 401 ve 403 Senaryolarını Karşılaştırın

Python’da teşhis için önemli olan yalnızca isteği göndermek değil, gönderilen isteğin hangi URL’ye, hangi metotla ve hangi başlıklarla gittiğini gözlemlemektir. Aşağıdaki örnek gerçek bir API sağlayıcısının davranışını taklit ettiğini iddia etmez. API_URL değişkenini kendi test sunucunuzdaki endpoint ile değiştirerek üç kontrollü varyasyonu karşılaştırabilirsiniz. Test sunucunuzun geçerli token, başlıksız istek ve yetersiz role nasıl yanıt vereceği ayrıca yapılandırılmalıdır.

import os
import requests

url = os.getenv("API_URL", "http://localhost:8000/protected")
tokens = {
    "gecerli": os.getenv("VALID_TOKEN", "valid-token"),
    "yetersiz_rol": os.getenv("LIMITED_TOKEN", "limited-token"),
}
for ad, token in [("başarılı", tokens["gecerli"]),
                  ("401 testi", None),
                  ("403 testi", tokens["yetersiz_rol"])]:
    headers = {"Authorization": f"Bearer {token}"} if token else {}
    response = requests.get(url, headers=headers, timeout=10)
    print(ad, response.status_code, response.text[:200])

Örneğin test sunucunuz geçerli token için 200, başlık bulunmayan istek için 401 ve kimlik doğrulaması yapılmış fakat yetersiz role sahip token için 403 döndürecek şekilde ayarlanmışsa, çıktı buna benzer bir desen gösterebilir:

başarılı 200 ...
401 testi 401 ...
403 testi 403 ...

Buradaki üç nokta, yanıt gövdesinin her API’de aynı olmayacağını özellikle belirtir. Bir sistem JSON hata nesnesi, başka bir sistem düz metin veya boş bir gövde döndürebilir. Ayrıca bazı uygulamalar farklı güvenlik politikaları nedeniyle benzer durumları farklı HTTP kodlarıyla gösterebilir. Bu yüzden kodu çalıştırdığınızda yalnızca beklenen sayısal kodu değil, yanıt başlıklarını, gövdeyi ve sunucu logundaki kararı da kaydedin. Requests yanıt nesnesi durum kodu ve metin gövdesi gibi alanlara erişim sağlar; JSON çözümleme işleminin başarılı olması ise HTTP isteğinin başarılı olduğu anlamına gelmez. ([requests.readthedocs.io](https://requests.readthedocs.io/en/latest/user/quickstart/?utm_source=openai))

Başlığın kaldırılması ile rolün değiştirilmesi arasındaki fark

headers = {} kullanıldığında istemci Authorization başlığını bu istek için göndermez. Sonuç olarak sunucu, isteği herhangi bir kullanıcı kimliği olmadan değerlendirebilir. Bu durum genellikle kimlik doğrulama katmanını test eder. Ancak istemcinin bir Session, middleware veya ortak istek fonksiyonu kullanması hâlinde başka bir katman başlığı yeniden ekleyebilir. Gerçek isteği doğrulamak için gerekirse hazırlanan request nesnesini inceleyin ve güvenli biçimde hangi başlıkların bulunduğunu kaydedin.

Yetersiz role sahip token kullanıldığında ise başlık hâlâ vardır ve sunucu token’dan bir kullanıcı bağlamı çıkarabilir. Değişen unsur, kullanıcının kaynak üzerinde yapabildiği işlemlerdir. Aynı URL ve metot için geçerli rol başarılı olurken sınırlı rol reddediliyorsa yetkilendirme politikası ön plana çıkar. Buna rağmen token’ın gerçekten farklı kullanıcıyı temsil ettiği, rol bilgisinin sunucuda güncel olduğu ve endpoint’in beklediği iznin dokümantasyonda veya sunucu yapılandırmasında doğrulandığı kontrol edilmelidir.

Python loglarında token güvenliği

Teşhis sırasında şu bilgileri yazdırmak genellikle yeterlidir:

•  
• İstek metodu ve URL’nin hassas sorgu parametreleri çıkarılmış hâli.
•  
• Authorization başlığının gönderilip gönderilmediği.
•  
• Token’ın tamamı yerine maskelenmiş ön eki veya karakter uzunluğu.
•  
• Yanıt kodu ve güvenli ölçüde kısaltılmış yanıt gövdesi.
•  
• Varsa correlation ID veya sunucu tarafından verilen izleme kimliği.
•  

Token’ın tamamını terminale, dosyaya, CI çıktısına veya hata izleme sistemine yazdırmayın. Bir token daha sonra geçersiz kılınsa bile geçmiş loglarda kalabilir. Python temellerini sistematik biçimde geliştirerek HTTP isteği, sözlük, döngü ve hata kontrolü gibi yapıların mantığını öğrenmek isteyenler için bire bir Python öğrenme kaynağı bu teşhis akışındaki kodu daha rahat uyarlamaya yardımcı olabilir.

Java İstemcilerinde Aynı Teşhis Mantığını Uygulayın

Java tarafında kütüphane veya framework değişse de teşhis mantığı aynıdır: üretilen HTTP isteğini görünür hâle getirin ve Python, Postman veya başka bir istemciyle karşılaştırın. Hata çözümü belirli bir metodu ezberlemekten çok, sunucuya ulaşan gerçek isteğin beklediğiniz istek olup olmadığını kanıtlamaya dayanır.

Bir Java HTTP istemcisinde request builder veya eşdeğer yapı üzerinden şu alanları ayrı ayrı inceleyin:

•  
• URL: Şema, host, port, path ve sorgu parametreleri aynı mı?
•  
• Metot: GET, POST, PUT, PATCH veya DELETE gerçekten beklediğiniz şekilde mi?
•  
• Authorization: Başlık var mı, değeri Bearer biçiminde mi, arada yanlış boşluk veya tırnak var mı?
•  
• Token: Test edilen kullanıcıya mı ait, süresi ve kapsamı doğrulanmış mı?
•  
• Yanıt kodu: Java istemcisi gerçek HTTP kodunu mu okuyor, yoksa yalnızca genel bir istisna mı gösteriyor?
•  
• Yanıt gövdesi: JSON, düz metin veya boş yanıt ayrımı korunuyor mu?
•  

Örneğin Postman’da çalışan bir isteği Java’ya taşırken yalnızca URL’yi kopyalamak yeterli değildir. Postman’ın otomatik eklediği başlıklar, ortam değişkenlerinden çözülen token, içerik türü ve yönlendirme davranışı Java istemcisinde aynı olmayabilir. Java request builder içinde oluşturulan isteği güvenli bir debug çıktısıyla kaydedin; token değerini maskeleyin ve ardından bu çıktıyı Postman’daki gerçek istekle satır satır karşılaştırın.

Python ve Java arasında çapraz kontrol listesi

1.  
2. Her iki istemcide de aynı ortamı, host adını ve endpoint path’ini kullanın.
3.  
4. HTTP metodunun ve varsa istek gövdesinin aynı olduğunu doğrulayın.
5.  
6. Authorization başlığının iki istemcide de gönderildiğini kontrol edin.
7.  
8. Token’ların aynı kullanıcıya ve aynı izin bağlamına ait olduğundan emin olun.
9.  
10. Yanıt kodlarını ve yanıt gövdelerini ayrı alanlar olarak kaydedin.
11.  
12. Fark varsa önce istemci tarafından üretilen gerçek isteği, sonra sunucu logunu inceleyin.
13.  

Python’da başarılı olan istek Java’da 401 dönüyorsa ilk şüpheleneceğiniz nokta token’ın sunucuya hiç ulaşmaması veya beklenen biçimde ulaşmamasıdır. Java’da 403 dönmesi, token’ın tanındığı fakat kullanıcı yetkisinin farklı olduğu anlamına gelebilir; ancak bu yorum, sunucu logu ve rol bilgisiyle doğrulanmalıdır. Tersine, iki istemcinin aynı URL, metot, header ve kullanıcıyla aynı sonucu vermesi, sorunun istemci kütüphanesinden çok sunucu tarafındaki kimlik veya yetki politikasında aranması gerektiğini düşündürür.

Maven veya Gradle bağımlılıkları ile HTTP istemci API’leri zaman içinde değişebildiğinden teşhis yöntemini belirli bir sürüm numarasına bağlamayın. Java öğrenme sürecinde request builder, header yönetimi, yanıt kodu ve hata gövdesi incelemesini uygulamalı olarak sürdürmek isteyenler için bire bir Java öğrenme kaynağı bu yaklaşımın temellerini pekiştirebilir.

Java tarafında güvenli gözlem

Debug logunda URL ve metot görülebilir; fakat sorgu parametrelerinde parola, API anahtarı veya kişisel veri bulunuyorsa bunları maskeleyin. Authorization başlığını “mevcut” veya “eksik” şeklinde işaretlemek çoğu teşhis için yeterlidir. Sunucu tarafından verilen izleme kimliği, yanıt kodu ve kısa hata gövdesi ise istemci ile sunucu loglarını eşleştirmeyi kolaylaştırır.

Teşhisi Tamamlamak İçin Yanıt Gövdesi ve Sunucu Logunu Birlikte Okuyun

HTTP durum kodu tek başına teşhis için yeterli değildir. 401 veya 403 sonucu, isteğin hangi aşamada reddedildiğine dair önemli bir ipucu verir; ancak hatanın gerçek nedenini anlamak için yanıt başlıklarını, yanıt gövdesini ve sunucu loglarını birlikte incelemek gerekir. Aynı 401 kodu geçersiz bir token, yanlış kimlik doğrulama şeması, hatalı endpoint veya kimlik doğrulama servisindeki bir uyuşmazlık nedeniyle dönebilir. Benzer biçimde 403, kullanıcının rolünün yetersiz olduğunu gösterebileceği gibi yanlış ortam, eksik scope veya sunucudaki erişim politikasının isteği engellediği anlamına da gelebilir.

Yanıt gövdesindeki hata ayrıntılarını nasıl değerlendirmelisiniz?

Önce yanıt gövdesini ham hâliyle kaydedin. JSON dönen bir API için aşağıdaki gibi alanlarla karşılaşabilirsiniz:

{
  "error": "insufficient_scope",
  "message": "The requested operation requires write access.",
  "request_id": "req-7f31a",
  "details": {
    "required_scope": "items:write"
  }
}

Bu alanların adları tüm API’lerde aynı olmak zorunda değildir. error, code, message, detail, request_id, trace_id veya correlation_id gibi farklı isimler kullanılabilir. Bu nedenle yalnızca belirli bir alanı aramak yerine, yanıtın tamamında şu bilgileri değerlendirin:

•  
• Genel hata kodu: Kimlik doğrulama mı, yetkilendirme mi, yoksa başka bir uygulama kuralı mı devreye girmiş?
•  
• Açıklama alanı: Token kabul edilmedi mi, gerekli izin bulunamadı mı, kaynak başka bir kullanıcıya mı ait?
•  
• Request veya correlation ID: Sunucu logunda aynı isteği bulmayı sağlayacak bir kimlik verilmiş mi?
•  
• Gerekli rol ya da scope: İstek için gereken izin açıkça belirtilmiş mi?
•  
• Alan adı veya ortam bilgisi: İstek test ortamına mı, üretim ortamına mı yönlenmiş?
•  

Hata açıklaması teşhis için yararlı olsa da doğrudan kesin kanıt olarak kabul edilmemelidir. Bazı sistemler güvenlik nedeniyle “geçersiz token”, “kullanıcı bulunamadı” veya “bu kaynağa erişemezsiniz” gibi ayrıntıları birbirinden ayırmadan genel bir mesaj döndürür. Bu yaklaşım, dışarıya fazla bilgi sızdırmamak için bilinçli olarak tercih edilebilir. Yanıt gövdesinde açıklama bulunmaması da tek başına sunucunun hatalı yapılandırıldığını göstermez; bu durumda loglar ve gönderilen gerçek istek daha önemli hâle gelir.

WWW-Authenticate başlığını kontrol edin

401 yanıtında WWW-Authenticate başlığı varsa, sunucunun hangi kimlik doğrulama şemasını veya meydan okuma bilgisini sunduğuna bakın. HTTP standardına göre 401 yanıtı üreten bir sunucunun en az bir kimlik doğrulama challenge’ı içeren bu başlığı göndermesi gerekir. Başlık tek bir şema içerebileceği gibi birden fazla challenge veya şemaya ait parametreler de içerebilir. ([rfc-editor.org](https://www.rfc-editor.org/rfc/inline-errata/rfc9110.html?utm_source=openai))

Örneğin WWW-Authenticate: Bearer ifadesi, kaynağın Bearer tabanlı bir erişim bilgisi beklediğini düşündürür. Bazı Bearer uygulamalarında başlıkta hata türü, açıklama veya kapsamla ilgili ek parametreler de bulunabilir. Fakat başlığın tam biçimi kullanılan kimlik doğrulama mekanizmasına ve API altyapısına göre değişebilir; bu nedenle yalnızca başlıkta “Bearer” kelimesini görmek tokenın doğru olduğunu kanıtlamaz. ([developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/WWW-Authenticate?utm_source=openai))

401 yanıtında bu başlık görünmüyorsa kontrolü hemen sonlandırmayın. Arada bir proxy, API gateway veya istemci kütüphanesi başlıkları değiştirmiş olabilir. Uygulama da güvenlik politikası veya özel hata işleme nedeniyle beklenen bilgiyi göndermiyor olabilir. Bu durumda Postman ya da istemci kodunda görülen yanıtı, mümkünse ağ katmanında alınan ham yanıtla ve sunucu loguyla karşılaştırın.

Sunucu loglarında hangi alanları aramalısınız?

Sunucu tarafında amaç, “istek neden reddedildi?” sorusunu kimlik doğrulama ve yetkilendirme aşamalarına ayırarak cevaplamaktır. Log alanlarının adı framework’e, gateway’e veya gözlemlenebilirlik sistemine göre değişebilir; ancak aşağıdaki bilgi grupları çoğu teşhis için yeterli bir çerçeve oluşturur:

1.  
2. Zaman: İsteğin sunucuya ulaştığı zaman damgasını ve mümkünse saat dilimini kontrol edin.
3.  
4. Endpoint ve metot: Gerçek URL yolu, HTTP metodu ve varsa sorgu parametrelerini inceleyin.
5.  
6. İstemci kimliği: Uygulama, servis, kullanıcı veya anonim istemci bilgisi kaydedilmiş mi bakın.
7.  
8. Kimlik doğrulama katmanı: Token ayrıştırıldı mı, imza doğrulandı mı, issuer veya audience kontrolü geçti mi?
9.  
10. Token durumu: Token süresi, iptal durumu, kapsamı veya ilgili oturum politikası kontrolünde ne sonuç alınmış?
11.  
12. Yetki modeli: Kullanıcı hangi rol, grup veya scope ile tanındı; endpoint hangi izinleri gerektiriyordu?
13.  
14. Reddetme nedeni: İstek kimlik doğrulamada mı, yetkilendirmede mi, kaynak erişim kuralında mı durduruldu?
15.  
16. Sonuç: Dönen HTTP kodu, uygulama hata kodu ve varsa gateway ile uygulama arasındaki farklı sonuçları karşılaştırın.
17.  

Örneğin logda tokenın imzasının doğrulandığı, kullanıcının başarıyla tanındığı ancak endpointin items:write scope’u istediği görülebilir. Bu gözlem 403 teşhisini destekler. Buna karşılık “Authorization header bulunamadı”, “token parser başarısız” veya “token süresi geçersiz” gibi kayıtlar 401 yönünde daha güçlü kanıt sağlar. Yine de uygulamanın kendi güvenlik politikasını dikkate alın; bazı sistemler farklı iç nedenleri dışarıya aynı HTTP koduyla yansıtabilir.

Token ve kişisel veriler loglara açık biçimde yazdırılmamalıdır

Teşhis amacıyla Authorization başlığını loglamak cazip görünür; ancak Bearer tokenın tamamı, parola, session cookie, API anahtarı, özel kullanıcı bilgileri veya gereksiz kişisel veriler düz metin olarak kaydedilmemelidir. Bu değerler hata ayıklama sırasında faydalı olsa bile log sistemine erişen yetkisiz bir kişinin oturumu kötüye kullanmasına yol açabilir. Güvenlik loglama rehberleri erişim tokenlarının, parolaların, oturum tanımlayıcılarının ve hassas kişisel verilerin kaldırılmasını, maskelenmesini veya güvenli biçimde dönüştürülmesini önerir. ([cheatsheetseries.owasp.org](https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html?utm_source=openai))

İhtiyaç varsa tokenın kendisi yerine güvenli bir parmak izi, son birkaç karakteri maskelenmiş bir tanımlayıcı veya yalnızca “header mevcut / eksik” gibi bir durum bilgisi kullanılabilir. Kullanıcı adı da teşhis için zorunlu değilse anonimleştirilebilir. Loglarda gerçek sırları aramak yerine, doğrulama sonucunu ve güvenli bir istek kimliğini aramak daha doğru yaklaşımdır.

İstemci logu ile sunucu logunu aynı istek üzerinden eşleştirin

Son kontrol adımı, Postman veya kod tarafında gördüğünüz isteği sunucu tarafındaki doğru log kaydıyla eşleştirmektir. Bunun için şu sırayı izleyin:

1.  
2. İstemcide yanıtın zamanını, URL’sini, HTTP metodunu ve durum kodunu kaydedin.
3.  
4. Yanıt başlıklarında request_id, trace_id, correlation_id veya benzer bir kimlik arayın.
5.  
6. Bu kimlik varsa sunucu logunda doğrudan arama yapın.
7.  
8. Kimlik yoksa zaman damgasını daraltın; endpoint, metot ve istemci bilgisiyle eşleşen kaydı bulun.
9.  
10. Gateway logu ile uygulama logunu ayrı ayrı karşılaştırın. İstek gateway’de 401, uygulamada ise 403 olarak kaydedilmiş olabilir.
11.  
12. Logdaki kimlik doğrulama ve yetkilendirme sonucunun istemcideki yanıt gövdesiyle uyumlu olup olmadığını kontrol edin.
13.  

Dağıtık sistemlerde correlation ID’nin farklı bileşenlere aktarılması, tek bir isteğin gateway, uygulama, kimlik doğrulama servisi ve veri katmanındaki izlerini birleştirmeye yardımcı olur. Uygulamalarda kullanılan başlık adı ve log alanı değişebilir; önemli olan aynı kimliğin istek boyunca korunmasıdır. ([learn.microsoft.com](https://learn.microsoft.com/en-us/azure/microsoft-discovery/concept-observability?utm_source=openai))

“Teşhis tamamlandı” kontrol listesi

•  
• İstek URL’si ve HTTP metodu sabitlenip doğrulandı mı?
•  
• Postman veya istemci kodunda gönderilen gerçek Authorization başlığı gözlemlendi mi?
•  
• Bearer tokenın varlığı, biçimi, süresi, hedefi ve ilgili doğrulama sonucu kontrol edildi mi?
•  
• Kimliği doğrulanan kullanıcı, client, rol, grup ve scope bilgileri incelendi mi?
•  
• İstenen endpoint için gereken izin ile mevcut izin karşılaştırıldı mı?
•  
• Yanıt gövdesindeki hata kodu, açıklama ve request ID değerlendirildi mi?
•  
• Varsa WWW-Authenticate başlığı incelendi mi?
•  
• Sunucu logu, reddetmenin kimlik doğrulama mı yoksa yetkilendirme aşamasında mı olduğunu destekliyor mu?
•  
• İstemci logu ile sunucu logu aynı zaman damgası veya request ID üzerinden eşleşiyor mu?
•  
• Teşhis sırasında token, parola ve kişisel verilerin loglara açık biçimde yazılmadığından emin olundu mu?
•  

Sık Sorulan Sorular

401 hatası her zaman token süresinin dolduğu anlamına mı gelir?

Hayır. Token süresinin dolması 401 nedenlerinden yalnızca biridir. Authorization başlığının hiç gönderilmemesi, Bearer biçiminin bozulması, token imzasının doğrulanamaması, yanlış issuer veya audience bilgisi, tokenın farklı bir ortam için üretilmiş olması ya da kimlik doğrulama servisinin isteği kabul etmemesi de 401 sonucuna yol açabilir. Kesin neden için yanıt gövdesini ve sunucu logundaki doğrulama aşamasını birlikte inceleyin.

Authorization başlığı gönderildiği hâlde neden 401 alınabilir?

Başlığın gönderilmiş olması, içindeki kimlik bilgisinin geçerli olduğu anlamına gelmez. Başlıkta Bearer yerine farklı bir şema kullanılmış olabilir, tokenın başında veya sonunda fazladan boşluk bulunabilir, yanlış token değişkeni okunabilir ya da istemci isteği beklenmeyen başka bir endpoint’e gönderebilir. Ayrıca proxy veya gateway başlığı uygulama sunucusuna aktarırken kaldırıyor olabilir. İstemcide gönderilen ham isteği ve sunucunun gerçekten aldığı başlığı güvenli biçimde karşılaştırın.

Kimlik doğrulaması başarılıyken 403 hatası neden döner?

Kimlik doğrulaması, isteği gönderen tarafın kim olduğunu belirler; yetkilendirme ise bu tarafın istenen işlemi yapıp yapamayacağını kontrol eder. Kullanıcı doğru biçimde tanınsa bile rolü endpoint için yetersiz olabilir, gerekli scope eksik olabilir, kaynak başka bir kullanıcıya ait olabilir veya işlem yalnızca belirli bir tenant, grup ya da ortam için açık olabilir. Bu nedenle 403 durumunda tokenı sürekli yenilemek yerine rol, scope, kaynak sahipliği ve erişim politikasını kontrol edin.

Postman'da çalışan istek Python veya Java kodunda neden 401 ya da 403 döndürebilir?

İki istemci aynı görünüyor olsa bile gerçek istekleri farklı olabilir. Kodda URL yolu, HTTP metodu, Authorization başlığı, token değeri, içerik türü, cookie, sorgu parametresi veya proxy ayarı değişmiş olabilir. Postman’da otomatik eklenen bir header ya da environment değişkeni kod tarafında bulunmayabilir. Teşhis için Postman’daki ham isteği kodun ürettiği ham istekle satır satır karşılaştırın; özellikle endpoint, metot, Authorization başlığı ve kullanılan tokenın aynı olduğundan emin olun.

401 ve 403 teşhisinde sunucu loglarında hangi bilgileri aramalıyım?

İstek zamanı, endpoint, HTTP metodu, istemci veya kullanıcı kimliği, kimlik doğrulama katmanının sonucu, tokenın güvenli biçimde özetlenmiş durumu, gerekli rol veya scope, reddetme nedeni, dönen durum kodu ve request ya da correlation ID aranmalıdır. Loglarda tokenın tamamı, parola, session cookie veya gereksiz kişisel veri bulunmamalıdır. İstemci yanıtındaki request ID’yi sunucu logunda arayarak aynı isteğin hangi katmanda reddedildiğini doğrulayın.

Bu yaklaşım, 401 ve 403 hatalarını tahmin ederek değil, gerçek isteği ve sunucunun kararını karşılaştırarak teşhis etmenizi sağlar.