API İsteklerinde 404 ve 500 Hataları Nasıl Teşhis Edilir?

API hata çözümü sürecinde 404 ve 500 durum kodlarını ayırmanın temel kuralı şudur: 404, sunucunun istenen URL’yi, route’u veya route üzerinden talep edilen kaynağı bulamadığını gösterir. 500 ise sunucu isteği işlerken beklenmeyen bir hata oluştuğunu; örneğin yakalanmamış bir istisnanın, uygulama mantığı probleminin, veritabanı işleminin veya harici bir bağımlılığın başarısız olduğunu anlatır.

İstemci yalnızca HTTP durum kodunu ve sunucunun gönderdiği yanıt gövdesini görür. Asıl hata nedeni ise çoğu zaman sunucu loglarında bulunur. Bu nedenle 500 yanıtını doğrudan “istemci yanlış istek gönderdi” diye yorumlamak doğru değildir; aynı şekilde her 404 de yalnızca URL’deki tek bir yazım hatasından kaynaklanmaz.

404 ve 500 Hatası Arasındaki Temel Fark Nedir?

Bir REST API isteğinde istemci, belirli bir HTTP methodu ile belirli bir adrese istek gönderir. Sunucu bu isteği önce uygun bir route ile eşleştirir, ardından path parametrelerini, başlıkları ve gövdeyi değerlendirerek uygulama kodunu çalıştırır. Hata teşhisinde hangi aşamada sorun oluştuğunu anlamak, 404 ile 500 arasındaki farkı doğru yorumlamayı sağlar.

404 Not Found çoğunlukla isteğin hedefinin bulunamadığını ifade eder. Bu hedef, hiç tanımlanmamış bir route olabileceği gibi doğru route içinde aranan bir kullanıcının veya siparişin bulunamaması da olabilir. Örneğin /users/999 adresine yapılan istek, /users/{id} route’una başarıyla ulaşabilir; ancak 999 kimlikli kullanıcı veritabanında yoksa uygulama yine 404 döndürebilir.

500 Internal Server Error ise isteğin sunucu tarafındaki işleme aşamasında beklenmeyen bir problem yaşandığını gösterir. Bu problem bir veritabanı bağlantı hatası olabilir; fakat 500 yalnızca veritabanı sorunlarına indirgenemez. Hatalı bir dönüşüm işlemi, beklenmeyen bir None değeri, dosya sistemi problemi, harici servisten gelen başarısız yanıtın yanlış ele alınması veya uygulama mantığındaki başka bir istisna da 500 ile sonuçlanabilir.

İstemcinin gördüğü hata ile sunucu logundaki hata neden farklıdır?

Bir API istemcisi genellikle şu tür bir yanıt görür:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
  "detail": "Internal server error"
}

Bu yanıt, geliştirici için çoğu zaman yalnızca bir başlangıç noktasıdır. Sunucunun loglarında aynı istek için çok daha ayrıntılı bir kayıt bulunabilir: hangi endpoint’in çağrıldığı, hangi kullanıcı veya istek kimliğiyle işlem yapıldığı, hangi fonksiyonun çalıştığı ve hangi istisnanın oluştuğu gibi bilgiler loglanmış olabilir.

Üretim ortamında stack trace, veritabanı sorgusu, dosya yolu, erişim anahtarı veya dahili servis adresi gibi hassas ayrıntılar istemciye gönderilmemelidir. İstemciye genel ve güvenli bir hata mesajı verilirken ayrıntılı teknik kayıtlar yalnızca yetkili ekiplerin erişebildiği log sisteminde tutulmalıdır.

404 her zaman yanlış URL, 500 her zaman veritabanı hatası mıdır?

Hayır. 404 için yanlış URL sık görülen bir nedendir; ancak tek olasılık değildir. Route doğru olsa bile path parametresi yanlış olabilir veya istenen kayıt silinmiş, taşınmış ya da hiç oluşturulmamış olabilir. Bu iki durumun ayrılması için “route’a ulaşılamadı” ile “route’a ulaşıldı fakat kaynak bulunamadı” ayrımını yapmak gerekir.

Benzer biçimde 500, yalnızca veritabanının kapalı olduğunu göstermez. Uygulama bir veritabanı sorgusundan dönen beklenmedik veri tipini işleyemediğinde, zorunlu bir alanı hatalı kullandığında veya başka bir API’den gelen yanıtı doğrulamadan işleme aldığında da sunucu içinde hata oluşabilir. Bu yüzden 500 teşhisi, istemci isteğinden başlayıp uygulama loglarına ve ilgili bağımlılıklara doğru ilerleyen bir inceleme gerektirir.

API kullanırken temel kavramları ne kadar doğru bildiğinizi görmek için ücretsiz yazılım bilgisi testi gibi kısa bir değerlendirme de yararlı olabilir. Böylece HTTP methodu, route, parametre ve yanıt kodu arasındaki ilişkide hangi noktaları tekrar etmeniz gerektiğini daha net görebilirsiniz.

404 Hatasını İstemci Tarafından Sistematik Olarak Kontrol Etme

404 aldığınızda doğrudan sunucu kodunu değiştirmeye başlamadan önce istemcinin gerçekten doğru isteği gönderdiğini doğrulayın. En verimli yaklaşım, isteği parçalarına ayırarak kontrol etmektir: tam URL, base URL ile route’un birleşimi, path parametresi, HTTP methodu, request body ve başlıklar. Bu sıralama, basit bir adres hatasını gereksiz sunucu incelemesiyle karıştırmanızı önler.

1. Tam URL’yi karakter karakter kontrol edin

Önce istemcinin gönderdiği tam adresi kopyalayarak kontrol edin. Alan adı, port numarası, API kök yolu, route adı, büyük-küçük harf kullanımı ve sondaki eğik çizgi gibi ayrıntılar bazı sunucu yapılandırmalarında önem taşıyabilir.

Örneğin uygulamanın gerçek endpoint’i /api/users iken istemci /users adresine istek gönderiyorsa, sunucu doğru uygulamaya ulaşsa bile eşleşen route bulamayabilir. Benzer şekilde /api/user ile /api/users farklı route’lar olarak tanımlanmış olabilir.

2. Base URL ve route birleşimini ayrı ayrı doğrulayın

İstemci kodlarında adres çoğu zaman iki parçadan oluşturulur:

BASE_URL = "https://api.example.com"
route = "/users/999"
url = BASE_URL + route

Bu yapı basit görünse de yanlış ortam adresi, eksik API prefix’i veya iki kez eklenen path bölümü 404 üretebilir. Örneğin base URL zaten /api ile bitiyorsa route içinde tekrar /api bulunması beklenmeyen bir adres oluşturabilir.

Kontrol sırasında yalnızca kodda yazan parçaları değil, ağ aracında gerçekten gönderilen tam URL’yi esas alın. Tarayıcı konsolu, Postman veya istemci kütüphanesinin istek günlüğü, birleştirilmiş adresi görmek için kullanılabilir.

3. Path parametresini ve kaynak varlığını ayırın

/users/999 gibi bir endpoint’te 999 değeri path parametresidir. Bu değerin yazım biçimi doğru olsa bile karşılık gelen kullanıcı kaydı bulunmayabilir. Bu durumda route’un kayıtlı olup olmadığı ile verinin mevcut olup olmadığı iki ayrı sorudur.

• Route hiç kayıtlı değilse, istek uygulamanın beklediği endpoint’e ulaşamıyor olabilir.
• Route kayıtlıysa, parametre uygulama içinde aranır ve kaynak bulunamadığında 404 dönebilir.
• Parametre sayısal beklenirken metin gönderilmesi, framework’e ve uygulama tasarımına göre farklı bir hata yanıtına yol açabilir.
• Kaynağın kimlik değeri doğru görünse bile yanlış ortamda, örneğin test veritabanında aranıyor olabilir.

Bu nedenle “404 aldım, URL kesin yanlış” demek yerine şu iki kontrolü ayrı yapın: Sunucu bu route’u tanıyor mu? Tanıyorsa istediğim kaynak bu ortamda gerçekten mevcut mu?

4. HTTP methodunu doğrulayın

Aynı path farklı HTTP methodlarıyla farklı işlemler ifade edebilir. GET /users/10 bir kaydı okumak için tanımlanmışken POST /users/10 veya DELETE /users/10 aynı şekilde karşılanmayabilir. Bazı sunucular bu durumda 405 gibi farklı bir durum kodu döndürür; bazı yönlendirme veya proxy yapılandırmalarında ise istemci beklemediği bir 404 görebilir.

Bu nedenle yalnızca adres çubuğundaki URL’yi değil, isteğin methodunu da kontrol edin. Özellikle Postman kullanırken seçili methodun GET, POST, PUT, PATCH veya DELETE seçeneklerinden hangisi olduğunu doğrulayın.

5. Postman isteğini parçalarına ayırarak okuyun

Postman’de teşhis yaparken isteğin methodu ve tam URL’si ilk kontrol noktasıdır. Ardından URL içindeki query parametrelerini, isteğin path parametrelerini, varsa request body içeriğini ve gönderilen başlıkları birlikte inceleyin. Yanıt bölümünde durum kodunu, yanıt gövdesini ve sunucunun gönderdiği açıklama alanlarını okuyun.

• Method: Route’un beklediği HTTP methoduyla aynı mı?
• URL: Base URL, port, API prefix’i ve route adı doğru mu?
• Params: Query parametreleri doğru isimle ve beklenen değerle mi gönderiliyor?
• Path: Kullanıcı veya kaynak kimliği doğru endpoint içinde mi?
• Headers: Gerekli Accept, Content-Type veya yetkilendirme başlıkları mevcut mu?
• Body: İstek gövdesi beklenen JSON yapısına sahip mi?
• Response: Yanıt gövdesi route bulunamadığını mı, yoksa belirli bir kaynağın bulunamadığını mı söylüyor?

Request body çoğu GET isteğinde temel 404 nedeni değildir; ancak yanlış header veya eksik kimlik doğrulama bazı API geçitlerinde isteğin beklenmeyen bir route’a yönlenmesine neden olabilir. Bu yüzden body ve başlıklar, URL ve method doğrulandıktan sonra incelenmelidir.

6. Kısa Python istemcisiyle yanıtı görünür hâle getirin

Aşağıdaki örnek, /user route’una istek gönderir ve 404 yanıtı geldiğinde durum kodu ile yanıt gövdesini birlikte yazdırır. Standart Python kütüphanesi kullandığı için ek paket gerektirmez:

from urllib.request import Request, urlopen
from urllib.error import HTTPError

url = "http://localhost:8000/user"
request = Request(url, method="GET")

try:
    with urlopen(request) as response:
        print(response.status)
        print(response.read().decode("utf-8"))
except HTTPError as error:
    print(error.code)
    print(error.read().decode("utf-8"))

Beklenen bir 404 yanıtı örneğin şöyle görünebilir:

404
{"detail": "User route not found"}

Buradaki gövde metni her API’de aynı olmak zorunda değildir. Önemli olan, istemcinin yalnızca “hata oldu” mesajına bakmaması; HTTP kodunu, yanıt gövdesini ve mümkünse istek izleme bilgisini birlikte değerlendirmesidir.

404 teşhisinde kısa kontrol listesi

1. Gönderilen tam URL’yi kopyalayıp karakter karakter kontrol edin.
2. Base URL ile route’un doğru ve yalnızca bir kez birleştiğinden emin olun.
3. HTTP methodunun route tanımıyla eşleştiğini doğrulayın.
4. Path parametresinin doğru biçimde ve doğru kaynak kimliğiyle gönderildiğini kontrol edin.
5. Route’un uygulamada kayıtlı olup olmadığını ayrı, kaynağın mevcut olup olmadığını ayrı değerlendirin.
6. Postman veya Python istemcisinde query parametrelerini, başlıkları ve request body’yi inceleyin.
7. Yanıt gövdesindeki açıklamanın route bulunamadığını mı, kaynak bulunamadığını mı belirttiğine bakın.
8. İstek doğru sunucuya gidiyor mu kontrol edin; test, geliştirme ve üretim ortamlarını karıştırmayın.

500 Hatasında Sunucu Loglarından Veritabanına İlerleyen Teşhis Akışı

500 Internal Server Error, sunucunun isteği işlerken beklenmeyen bir istisna veya iç işlem hatasıyla karşılaştığını gösterir. İstemcide URL’yi birkaç kez değiştirmek, aynı isteği Postman ile yeniden göndermek ya da sayfayı yenilemek bu hatayı otomatik olarak çözmez. İstek sunucuya ulaşıyor olabilir; sorun, route çalıştıktan sonra uygulama kodunda, veritabanında veya başka bir bağımlılıkta ortaya çıkabilir.

Teşhis sırasında amaç yalnızca “500 döndü” demek değil, hatanın hangi katmanda oluştuğunu daraltmaktır. Bunun için kontrol sırası şu şekilde korunmalıdır: URL, path parametresi ve HTTP methodu; route kaydı; request body ve başlıklar; uygulama logları; veritabanı ve harici bağımlılıklar.

1. URL, path parametresi ve HTTP methodunu doğrulayın

Görülen belirti: İstemci 500 alır; ancak istek beklenenden farklı bir URL’ye, yanlış bir path parametresiyle veya yanlış HTTP methoduyla gönderilmiş olabilir. Bazı uygulamalarda bu uyumsuzluk doğrudan 404 ya da 405 üretirken, hatalı route tasarımı nedeniyle sunucu içinde istisnaya da dönüşebilir.

Kontrol edilecekler:

• İstek gerçekten beklenen temel URL’ye mi gönderiliyor?
• /users/999 ile /user/999 gibi tekil-çoğul route farkı var mı?
• Path parametresi beklenen veri tipinde mi? Örneğin sayısal kullanıcı kimliği yerine metin gönderilmiş olabilir.
• GET yerine POST, PUT yerine PATCH veya DELETE yerine GET kullanılmış olabilir mi?
• Sonunda bulunan veya bulunmayan eğik çizgi route eşleşmesini etkiliyor mu?
• İstemci, farklı bir ortamın adresine mi bağlanıyor? Geliştirme, test ve üretim adresleri karıştırılmış olabilir.

Çıkarılabilecek sonuç: URL veya method yanlışsa uygulamanın iş mantığına geçmeden önce isteği düzeltmek gerekir. Route gerçekten bulunamıyorsa doğru sonuç çoğunlukla 404 veya method desteklenmiyorsa uygun bir 405 yanıtıdır. Buna karşılık doğru endpoint ve method kullanıldığı hâlde 500 devam ediyorsa sonraki aşamaya geçilir.

2. Route kaydının gerçekten çalıştığını kontrol edin

Görülen belirti: İstek doğru göründüğü hâlde sunucu 500 döndürür. Bu durumda route kaydı mevcut olabilir fakat route içindeki fonksiyon çağrılmadan önce bir import, middleware veya yapılandırma hatası oluşabilir. Route çalışıyor gibi görünse bile hangi kod yolunun tetiklendiği doğrulanmalıdır.

Kontrol edilecekler:

• İlgili endpoint uygulamada gerçekten kayıtlı mı?
• Route, beklenen HTTP methodunu kabul ediyor mu?
• Route’un bağlı olduğu controller, handler veya view fonksiyonu yüklenebiliyor mu?
• Route parametresinin adı ile handler içindeki parametre adı uyumlu mu?
• Kimlik doğrulama, yetkilendirme, CORS veya diğer middleware katmanları isteği değiştirebilir mi?
• Route kaydı yalnızca belirli bir ortam değişkeni veya özellik bayrağı açıkken mi etkinleşiyor?

Çıkarılabilecek sonuç: Route hiç eşleşmiyorsa 404 beklenir. Route eşleşiyor fakat handler’a ulaşmadan hata oluşuyorsa uygulamanın başlangıç kayıtları, middleware zinciri veya modül yükleme süreci incelenmelidir. Handler’a ulaşıldığı biliniyorsa teşhis request body ve başlıklara taşınır.

Bu aşamaları yalnızca hata çıktısını okuyarak değil, kontrollü isteklerle ve adım adım ilerleyerek öğrenmek isteyenler için canlı sınıflı yazılım eğitimleri içinde API isteklerinin istemci-sunucu akışını uygulamalı biçimde incelemek yararlı olabilir.

3. Request body ve başlıkları inceleyin

Görülen belirti: Özellikle POST, PUT ve PATCH isteklerinde sunucu 500 döndürür. İstek gövdesi eksik, hatalı biçimde veya uygulamanın beklediği veri tiplerinden farklı gönderilmiş olabilir. Başlangıç düzeyinde sık yapılan hata, geçersiz bir JSON gövdesini sunucunun iç hatası sanmaktır.

Kontrol edilecekler:

• Gönderilen body geçerli JSON biçiminde mi?
• Content-Type: application/json başlığı gönderiliyor mu?
• Beklenen zorunlu alanlar mevcut mu?
• Alan adları doğru mu? userId yerine user_id bekleniyor olabilir.
• Sayısal olması gereken alana metin, tarih alanına geçersiz biçim veya dizi alanına tek bir değer gönderilmiş olabilir mi?
• Kimlik doğrulama için gerekli Authorization ya da özel istemci başlığı mevcut mu?
• Body’nin kodlanması, karakter seti veya içerik uzunluğu sunucunun beklentisiyle uyumlu mu?

Çıkarılabilecek sonuç: Gövde veya başlıklar geçersizse ideal API tasarımında 400 ya da 422 gibi istemci hatası döndürülmelidir. Ancak uygulama doğrulama yapmadan veriyi işleme sokuyor ve istisnayı yakalamıyorsa aynı durum 500 olarak görünebilir. Bu nedenle istemcinin hatalı veri gönderdiği düşünülse bile, sunucu loglarında bu verinin nasıl işlendiği kontrol edilmeden kesin sonuca varılmamalıdır.

4. Uygulama loglarında zaman, istek kimliği ve çağrı zincirini eşleştirin

Görülen belirti: İstemci yalnızca genel bir 500 mesajı görür. Response body içinde çoğu zaman gerçek exception türü, dosya adı veya veritabanı ayrıntısı bulunmaz. Bu ayrıntılar istemciye gönderilmemeli; geliştirici incelemesi için sunucu tarafındaki loglarda tutulmalıdır.

Kontrol edilecekler:

• İsteğin gerçekleştiği timestamp ile log kaydının zamanı eşleşiyor mu?
• Her istek için üretilen request ID veya correlation ID loglarda bulunuyor mu?
• Exception türü nedir? Örneğin tür dönüşümü, anahtar bulunamaması, bağlantı veya zaman aşımı hatası olabilir.
• Çağrı zincirinde hata hangi dosya, fonksiyon veya servis çağrısında oluşmuş?
• Hata tek bir kullanıcı veya endpoint ile mi sınırlı, yoksa aynı anda birçok istekte mi görülüyor?
• Hatadan hemen önce dış servise, veritabanına veya dosya sistemine yapılan bir çağrı var mı?

Çıkarılabilecek sonuç: Loglarda uygulama exception’ı görülüyorsa 500 hatasının kaynağı artık istemci katmanı değil, sunucudaki belirli bir işlem adımıdır. Örneğin ValueError veri dönüşümünü, KeyError beklenen alanın bulunamadığını, bağlantı veya timeout hatası ise bir bağımlılığa erişim problemini işaret edebilir. Exception adını görmek tek başına yeterli değildir; çağrı zincirinde hatanın ilk oluştuğu noktaya kadar ilerlemek gerekir.

İstemciye gönderilebilecek yanıt ile sunucuda tutulması gereken teşhis kaydı birbirinden ayrılmalıdır. İstemciye örneğin aşağıdaki gibi genel bir yanıt gönderilebilir:

{
  "error": "internal_server_error",
  "message": "Beklenmeyen bir sunucu hatası oluştu.",
  "request_id": "req-8f31"
}

Geliştiricinin incelediği güvenli log kaydı ise timestamp, request ID, exception türü, çağrı zinciri ve varsa bağımlılık yanıtının durumunu içerebilir. Buradaki amaç, kullanıcıya veritabanı adresi, erişim anahtarı, SQL sorgusundaki hassas değerler veya ayrıntılı stack trace göstermeden hatayı yeniden üretebilmektir. Loglama altyapısına göre request ID ve hata kayıtlarının üretim biçimi değişebileceği için uygulamanın kullandığı yapılandırma ayrıca incelenmelidir.

5. Veritabanı ve harici bağımlılıkları ayrı ayrı doğrulayın

Uygulama loglarında hata bir veritabanı sorgusundan veya dış servise yapılan çağrıdan sonra görünüyorsa, tüm problemi “API bozuk” şeklinde değerlendirmek yerine bağımlılıkları tek tek ayırmak gerekir. Bir endpoint’in 500 dönmesi, API kodunun her zaman hatalı olduğu anlamına gelmez; veritabanı bağlantısı, yetki, şema uyumsuzluğu veya dış servisin verdiği beklenmeyen yanıt da aynı sonucu doğurabilir.

Bağlantı bilgileri kontrol edilirken gizli değerler doğrudan loglanmamalıdır. Host veya bağlantı profilinin adı kayda alınabilir; parola, token ve tam bağlantı dizesi maskelenmelidir. Timeout incelemesinde ise hatanın bağlantı kurulurken mi, sorgu çalışırken mi, yoksa dış servisten yanıt beklenirken mi oluştuğu ayrıştırılmalıdır.

Veritabanına erişim başarılı olduğu hâlde hata devam ediyorsa sorgunun döndürdüğü veri ile uygulamanın beklediği veri modeli karşılaştırılmalıdır. Örneğin uygulama her kullanıcı kaydında email alanı olduğunu varsayıyor, ancak bazı eski kayıtlarda bu alan boş geliyorsa, sorgu başarılı olsa bile sonrasındaki kod bir istisna üretebilir.

Harici API’lerde yalnızca 2xx yanıtları değil, 4xx ve 5xx yanıtları da ele alınmalıdır. Dış servis 404 döndürdüğünde bunu kendi API’sinin 500 hatasına dönüştürmek yerine anlamlı bir iç hata modeli oluşturmak daha sağlıklıdır. Dış servisin yanıt gövdesi beklenen JSON yerine HTML, boş içerik veya farklı bir JSON şeması içeriyorsa ayrıştırma kodu da incelenmelidir.

500 teşhis karar ağacının ana gövdesi

1. Route bulundu mu? Hayırsa sonuç 404 olarak değerlendirilir ve URL, method veya route kaydı düzeltilir.
2. Route bulunduysa path parametresi ve request body geçerli mi? Geçerli değilse uygun istemci yanıtı, genellikle 400, 405 veya 422 sınıfından biri olmalıdır.
3. Parametre ve gövde geçerliyse uygulama loglarına ilerleyin. Aynı request ID ile isteğin tüm çağrı zincirini takip edin.
4. Yakalanmamış bir istisna var mı? Varsa exception’ın ilk oluştuğu fonksiyonu ve ilgili veri akışını izole edin.
5. Hata bir bağımlılıkta mı oluşuyor? Veritabanı veya harici servis için bağlantı, timeout, yetki, şema ve yanıt biçimini ayrı ayrı doğrulayın.
6. Bağımlılık sağlıklıysa uygulama mantığına, veri dönüşümlerine, null değer kullanımına ve hata yakalama sınırlarına geri dönün.

Bu akışta 500 yanıtı bir teşhis sonucu değil, incelemenin başlangıç sinyalidir. İstemci yalnızca status code ve güvenli hata gövdesini görür; asıl neden, request ID üzerinden sunucu logları ve bağımlılık kayıtları birlikte incelenerek bulunur.

Postman ve Python İstemcisiyle 404 ve 500 Yanıtlarını Karşılaştırma

Postman ve Python istemcisi aynı endpoint’e benzer istekler gönderdiğinde temel olarak üç bilgi karşılaştırılır: status_code, response body ve temel response header değerleri. Bu bilgiler istemcinin ne gördüğünü açıklar; ancak 500 hatasının nedenini tek başına göstermez. Nedenin bulunması için aynı isteğin timestamp’i ve request ID’si sunucu loglarında aranmalıdır.

Postman’da karşılaştırılacak alanlar

Postman ile önce kaynak bulunamadığında beklenen endpoint, ardından sunucuda kontrollü hata üreten test endpoint’i çağrılabilir. Her iki istekte de method, URL, path parametresi, body ve başlıklar aynı mantıkla incelenmelidir.

• Status: Kaynak yoksa 404, beklenmeyen sunucu hatasında 500 görülür.
• Response body: 404 için kaynak bulunamadığını belirten güvenli bir mesaj; 500 için genel bir sunucu hatası mesajı beklenir.
• Headers: İçerik tipi, request ID ve önbellekleme davranışı gibi temel bilgiler kontrol edilir.
• Sunucu kaydı: 500 için timestamp, request ID, exception ve çağrı zinciri ayrıca aranır.

Çalıştırılabilir kısa Python API örneği

Aşağıdaki örnek, harici bir Python paketi gerektirmeden standart kütüphane ile küçük bir HTTP sunucusu çalıştırır. /users/999 yolu 404 döndürür. /crash yolunda endpoint mantığı içinde yakalanmayan bir istisna oluşur; HTTP sunucusunun hata sınırı bu istisnayı güvenli bir 500 yanıtına çevirir ve ayrıntıyı sunucu konsoluna yazar.

from http.server import BaseHTTPRequestHandler, HTTPServer
import json, traceback

class API(BaseHTTPRequestHandler):
    def reply(self, code, data):
        body = json.dumps(data).encode()
        self.send_response(code)
        self.send_header("Content-Type", "application/json")
        self.end_headers()
        self.wfile.write(body)

    def do_GET(self):
        try:
            if self.path == "/users/999":
                self.reply(404, {"error": "user_not_found"})
            elif self.path == "/crash":
                raise RuntimeError("demo exception")
            else:
                self.reply(200, {"message": "ok"})
        except Exception:
            traceback.print_exc()
            self.reply(500, {"error": "internal_server_error"})

HTTPServer(("localhost", 8000), API).serve_forever()

Sunucuyu çalıştırdıktan sonra Postman’da veya tarayıcıda iki farklı endpoint denenebilir. Aynı istekleri Python ile göndermek için standart kütüphanedeki urllib.request kullanılabilir:

from urllib.request import urlopen
from urllib.error import HTTPError

for path in ("/users/999", "/crash"):
    try:
        with urlopen("http://localhost:8000" + path) as response:
            print(path, response.status, response.read().decode())
    except HTTPError as error:
        print(path, error.code, error.read().decode())

Beklenen 404 yanıtı

/users/999 404 {"error": "user_not_found"}

Bu çıktı, isteğin sunucuya ulaştığını ancak istenen kullanıcı kaydının bulunamadığını gösterir. Burada URL route’u doğru olabilir; bulunamayan şey route değil, route’un aradığı kaynaktır. Gerçek uygulamalarda kaynak bulunamadığında 404 yanıtının hangi durumlarda verileceği API tasarımına bağlıdır, fakat istemci bu sonucu sunucu içi exception ile karıştırmamalıdır.

Beklenen 500 yanıtı

/crash 500 {"error": "internal_server_error"}

Bu çıktı, istemcinin yalnızca güvenli ve genel hata mesajını gördüğünü gösterir. Aynı anda sunucunun çalıştığı terminalde exception türü ve çağrı zinciri görüntülenir. Üretim ortamında bu ayrıntılar response body’ye eklenmemelidir; çünkü dosya yolları, SQL parçaları, yapılandırma bilgileri veya hassas kullanıcı verileri açığa çıkabilir.

Postman ve Python çıktısını nasıl yorumlamalısınız?

Kısa kontrol listesi şu şekilde kullanılabilir:

• Postman ve Python aynı URL’ye mi istek gönderiyor?
• HTTP methodu ve path parametresi aynı mı?
• Response status code beklenen sonucu veriyor mu?
• Response body genel ve güvenli mi?
• 500 durumunda request ID ile sunucu logu eşleştirildi mi?
• Loglarda exception’ın kaynağı uygulama kodu mu, veritabanı mı, harici servis mi?

Postman’da 404 ile 500 arasındaki farkı görmek, HTTP durum kodlarını ezberlemekten daha değerlidir. 404 genellikle route veya kaynak çözümleme aşamasındaki bir problemi; 500 ise sunucunun geçerli görünen isteği işlerken beklenmeyen bir iç hatayla karşılaşmasını anlatır. Bu ayrımı yaptıktan sonra istemci çıktısını sunucu loglarıyla eşleştirmek, API hata çözümünü rastgele denemelerden sistematik bir teşhis sürecine dönüştürür.

Üretimde Güvenli Hata Yanıtı ve Uygulanabilir Karar Ağacı

API hatalarını geliştirirken ayrıntılı hata çıktıları teşhis sürecini hızlandırabilir. Stack trace, dosya yolu, sorgu bilgisi ve değişken içerikleri geliştirici için sorunun kaynağını anlamayı kolaylaştırır. Ancak üretim ortamında bu ayrıntıların doğrudan istemciye gönderilmesi güvenli değildir. İstemciye kısa, tutarlı ve hassas bilgi içermeyen bir hata mesajı; uygun HTTP durum kodu ve mümkünse destek ekibinin loglarla eşleştirebileceği bir request ID dönülmelidir.

Geliştirme ve üretim ortamında hata yanıtı neden farklı olmalıdır?

Geliştirme ortamında amaç hatanın neden oluştuğunu hızlıca bulmaktır. Bu nedenle ayrıntılı loglar, exception türü, çağrı zinciri ve ilgili modül bilgileri geliştirici ekranında görülebilir. Yine de bu bilgilerin API yanıtına nasıl yansıtılacağı dikkatle kontrol edilmelidir.

Üretim ortamında ise API yanıtı, uygulamanın iç yapısını dışarıya açmamalıdır. Aşağıdaki bilgiler istemciye gönderilmemelidir:

• Stack trace ve exception çağrı zinciri
• Sunucudaki gerçek dosya yolları
• SQL sorguları, tablo adları veya veritabanı bağlantı ayrıntıları
• API anahtarları, erişim belirteçleri ve bağlantı bilgileri
• İç servis adları, ağ adresleri veya altyapı topolojisi
• Başka kullanıcıların verileri ya da isteğe ait gereksiz hassas alanlar

Güvenli bir üretim yanıtı, geliştiriciye yeterli teşhis bağlantısı sunarken istemciye yalnızca gerekli bilgiyi vermelidir. Örneğin sunucu içinde ayrıntılı exception loglanabilir; istemciye ise “İstek işlenirken beklenmeyen bir hata oluştu” mesajı ve benzersiz bir request ID dönebilir.

Güvenli 404 ve 500 yanıtı nasıl tasarlanır?

404 yanıtında istemciye, istenen kaynağın bulunamadığı bilgisi verilebilir. Ancak yanıtın, sistemde hangi kullanıcıların veya kayıtların bulunduğu hakkında gereksiz ipucu üretmemesi gerekir. 500 yanıtında ise iç hata mekanizması gizlenmeli, istemciye genel bir mesaj verilmelidir.

Örneğin güvenli bir 404 yanıtı şu yapıda olabilir:

{
  "error": "resource_not_found",
  "message": "İstenen kaynak bulunamadı.",
  "request_id": "req-8f31c2"
}

Beklenmeyen bir sunucu hatası için ise şu tür bir yanıt tercih edilebilir:

{
  "error": "internal_server_error",
  "message": "İstek işlenirken beklenmeyen bir hata oluştu.",
  "request_id": "req-a17d09"
}

Buradaki request_id değeri, istemcinin destek ekibine iletebileceği bir takip anahtarıdır. Sunucu loglarında aynı değerle arama yapıldığında ilgili istek, hata kaydı ve zaman bilgisi bulunabilir.

Request ID uygulaması, belirli bir framework ayarına bağlı olmak zorunda değildir. Uygulama, isteğin başlangıcında bir kimlik üretebilir veya güvenilir bir proxy tarafından sağlanan değeri kontrollü biçimde kullanabilir. Daha sonra bu değer response header'ına, yapılandırılmış loglara ve gerektiğinde JSON hata gövdesine eklenebilir. Önemli olan, request ID'nin parolalar veya erişim belirteçleri gibi gizli bir bilgi olarak kullanılmaması ve loglarda tutarlı biçimde taşınmasıdır.

Hata gövdesinin alanlarını, durum kodlarını ve istemci davranışlarını ekip içinde ortaklaştırmak için API hata yanıtları hakkında sık sorulan sorular gibi referans niteliğinde bir dokümantasyon yapısı da kullanılabilir. Böylece geliştirici, test yapan kişi ve istemci uygulaması aynı hata sözleşmesini izler.

404'ten 500'e ilerleyen karar ağacı

Bir API isteği başarısız olduğunda doğrudan sunucu kodunu değiştirmek yerine aşağıdaki sırayla ilerlemek daha sağlıklıdır. Her adım, bir önceki ihtimali elemeden sonraki katmana geçmeyi önler.

1. İstek doğru sunucuya mı gidiyor?

   Base URL, ortam adresi, port, proxy ve kullanılan alan adı kontrol edilir. İstemci geliştirme sunucusu yerine test veya üretim sunucusuna gidiyor olabilir. Yanıt başlıkları, sunucu bilgisi ve zaman damgası da isteğin beklenen ortama ulaşıp ulaşmadığı konusunda ipucu verebilir.

2. Route kayıtlı mı?

   İstek yolu, uygulamadaki route tanımıyla birebir karşılaştırılır. Büyük-küçük harf farkı, çoğul-tekil kaynak adı, eksik bir ön ek veya sürüm yolu gibi ayrıntılar 404 oluşturabilir. Örneğin /users/12 ile /user/12 aynı route olmak zorunda değildir.

3. HTTP methodu doğru mu?

   Aynı path için yalnızca GET tanımlanmışken POST, PUT veya DELETE gönderilmesi beklenmeyen sonuçlara yol açabilir. İstek yolu doğru görünse bile method yanlışsa route eşleşmesi başarısız olabilir veya uygulama farklı bir işlem akışına girebilir.

4. Parametre ve kaynak geçerli mi?

   Path parametresinin biçimi, sorgu parametrelerinin adları ve istenen kaydın gerçekten bulunup bulunmadığı incelenir. id alanına sayı beklenirken metin gönderilmesi, geçersiz bir UUID kullanılması veya silinmiş bir kaydın çağrılması bu aşamada fark edilebilir.

5. Body ve başlıklar beklenen biçimde mi?

   JSON gövdesinin söz dizimi, zorunlu alanları, veri tipleri ve Content-Type başlığı kontrol edilir. Kimlik doğrulama gerekiyorsa token'ın gönderilip gönderilmediği ve doğru başlıkta bulunup bulunmadığı da incelenmelidir. Hatalı bir body çoğu API'de 4xx yanıtına neden olur; ancak hatalı doğrulama veya eksik hata yönetimi sunucu tarafında 500'e de dönüşebilir.

6. Uygulama logunda istisna var mı?

   Yanıt kodu 500 ise sunucu logları, request ID ve istek zamanı birlikte aranır. Exception türü, hatanın oluştuğu modül, çağrı zinciri ve hangi işlem sırasında hata alındığı belirlenir. İstemcinin gönderdiği hata mesajı tek başına 500'ün kök nedenini açıklamayabilir.

7. Veritabanı veya harici bağımlılık yanıt veriyor mu?

   Veritabanı bağlantısı, sorgu sonucu, transaction durumu, timeout bilgisi ve bağlantı havuzu incelenir. Ardından ödeme servisi, kimlik sağlayıcı, dosya depolama sistemi veya başka bir harici API gibi bağımlılıkların erişilebilirliği kontrol edilir. Uygulama mantığı doğru olsa bile bu katmanlardan birinin yanıt vermemesi 500'e veya uygun şekilde ele alınmışsa başka bir hata yanıtına neden olabilir.

Bu akışta 404 ile 500 arasındaki ayrım önemlidir. Route bulunamıyorsa uygulamanın iş mantığına ulaşmadan önce sorun çözülmelidir. Route çalışıyor, fakat iş akışı sırasında yakalanmamış exception oluşuyorsa teşhis sunucu loglarına, veritabanına veya harici bağımlılıklara taşınır. 500 istemci hatası değildir; istemcinin gönderdiği veri süreci tetiklemiş olsa bile 500, sunucunun beklenmeyen bir durumu doğru biçimde yönetemediğini gösterir.

Uygulanabilir kısa kontrol listesi

Bir API isteğini incelemeye başlamadan önce aşağıdaki listeyi sırayla kullanabilirsiniz:

• URL: İstek doğru ortam, alan adı, port ve API ön ekine mi gidiyor?
• Method: GET, POST, PUT, PATCH veya DELETE seçimi route tanımıyla uyumlu mu?
• Parametre: Path ve query parametreleri doğru isimde, biçimde ve değerde mi?
• Body: JSON geçerli mi, zorunlu alanlar mevcut mu, veri tipleri beklenen yapıda mı?
• Headers: Content-Type, Authorization ve gerekli özel başlıklar gönderiliyor mu?
• Route: Uygulamada ilgili method ve path gerçekten kayıtlı mı?
• Log: Request ID ile eşleşen bir exception veya hata kaydı var mı?
• Database: Bağlantı, sorgu, transaction ve kayıt durumu normal mi?
• Dependency: Harici servis, dosya sistemi veya mesajlaşma bileşeni yanıt veriyor mu?
• Güvenli response: İstemciye stack trace veya hassas altyapı ayrıntısı sızıyor mu?

Kontrol listesinin son maddesi yalnızca güvenlik için değil, hata sözleşmesinin sürdürülebilirliği için de önemlidir. İstemci uygulaması, her sunucu değişikliğinde farklılaşan exception metinlerine değil; kararlı durum kodlarına, hata kodlarına ve gerektiğinde request ID değerine dayanmalıdır.

Sık Sorulan Sorular

404 hatası alıyorsam sorun her zaman URL'nin yanlış olması mı?

Hayır. URL'nin yanlış olması yaygın nedenlerden biridir; ancak route'un kayıtlı olmaması, HTTP methodunun uyuşmaması, path parametresinin hatalı olması veya istenen kaynağın bulunamaması da 404 sonucuna yol açabilir. Base URL, route tanımı, method, parametre ve kaynak durumu birlikte kontrol edilmelidir.

Bir API isteğinde 500 hatasını düzeltmek için istemci tarafında hangi kontrolleri yapmalıyım?

Önce URL, HTTP methodu, path parametreleri, request body, Content-Type ve Authorization başlığını kontrol edin. JSON gövdesinin geçerli olduğundan ve zorunlu alanların doğru veri tipleriyle gönderildiğinden emin olun. Bu kontroller doğruysa 500'ün kök nedeni büyük olasılıkla sunucu tarafındaki uygulama mantığı, veritabanı veya harici bir bağımlılıktadır; çözüm için request ID ile sunucu logları incelenmelidir.

Postman'de 500 görüyorum; geliştirici sunucu loglarında hangi bilgileri aramalı?

İstek zamanı, HTTP methodu, path, request ID, exception türü, çağrı zinciri, hatanın oluştuğu uygulama modülü ve veritabanı ya da harici servis çağrısının sonucu aranmalıdır. Request body içinde parola, token veya kişisel veri bulunuyorsa loglama sırasında bu alanların maskelenmiş olduğundan emin olun. Tek başına Postman'deki “500 Internal Server Error” metni kök nedeni belirlemek için yeterli değildir.

Üretimde stack trace'i API yanıtında göstermek neden sakıncalıdır?

Stack trace; dosya yolları, sınıf ve fonksiyon adları, kullanılan kütüphaneler, sorgular veya altyapı bileşenleri hakkında istem dışı bilgi verebilir. Bu ayrıntılar uygulamanın iç yapısını açığa çıkarabileceği gibi erişim bilgileri ya da hassas veri sızıntısına da neden olabilir. Üretimde ayrıntılı hata geliştirici loglarında tutulmalı; istemciye uygun durum kodu, genel hata mesajı ve gerekiyorsa request ID gönderilmelidir.

Doğru teşhis, yalnızca hatayı ortadan kaldırmak değil; aynı zamanda istemciye güvenli, sunucu ekibine ise izlenebilir bir hata yanıtı sunmaktır.