HTTP 400 mü 422 mi? API Hatalarını Ayırt Etme

HTTP 400 ve 422 arasındaki temel fark, isteğin hangi aşamada başarısız olduğudur. İstek HTTP düzeyinde bozuksa veya gövde parse edilemiyorsa genellikle 400 Bad Request kullanılır; istek okunabiliyor, içerik türü anlaşılabiliyor ve JSON sözdizimi geçerli olduğu hâlde içerik doğrulamadan geçemiyorsa 422 Unprocessable Content değerlendirilebilir.

Bu ayrım tüm framework’lerde otomatik olarak aynı uygulanmaz. API sözleşmesi, kullandığınız framework’ün varsayılan davranışı ve istemcilerin hata gövdelerini nasıl işlediği birlikte düşünülmelidir. Pratik teşhis için şu sırayı kullanın: HTTP biçimi → JSON yapısı → alan tipi → zorunlu alan → iş kuralı.

400 mü 422 mi? Önce Hatanın Hangi Katmanda Olduğunu Bulun

Bir API isteğini yalnızca “başarılı” veya “başarısız” diye değerlendirmek yerine, sunucunun isteği ne kadar ilerletebildiğini incelemek daha sağlıklıdır. Sunucu HTTP mesajını okuyamıyor, istek gövdesini çözemiyor veya içerik sözdizimsel olarak geçersizse problem henüz uygulama doğrulamasına ulaşmamıştır. Bu tür durumlarda 400 daha anlaşılır bir seçimdir.

Buna karşılık sunucu isteğin içerik türünü ve yapısını anlayabiliyor, JSON nesnesini okuyabiliyor fakat gönderilen değerler beklenen kurallara uymuyorsa 422 seçeneği gündeme gelir. Örneğin age alanının metin olarak gönderilmesi, zorunlu email alanının eksik bırakılması veya mevcut bir kullanıcı adıyla kayıt açılmaya çalışılması aynı katmanda oluşan hatalar değildir; ancak bunların ortak noktası, sunucunun isteği okuyabildiği hâlde içeriği işleyememesidir.

RFC 9110 HTTP Semantics, 400 kodunu istemci hatası olarak algılanan bozuk istek sözdizimi veya geçersiz mesaj çerçevesi gibi durumlarla ilişkilendirir. Aynı standartta 422 Unprocessable Content, içerik türü anlaşıldığında ve içerik sözdizimsel olarak doğru olduğunda, ancak içerilen talimatlar işlenemediğinde kullanılabilecek bir durum kodu olarak tanımlanır.

Yine de 422 kullanmak her API için zorunlu bir tercih değildir. Bazı ekipler eksik alan, hatalı tip ve iş kuralı ihlallerini tek bir 400 yanıtında toplar. Bu yaklaşım teknik olarak uygulanabilir; önemli olan hata sözleşmesinin baştan belirlenmesi, tutarlı kalması ve istemciye düzeltme yapabileceği bilgiyi vermesidir.

API Doğrulamasını Beş Katmana Ayırın

400 ve 422 ayrımını kolaylaştırmak için doğrulamayı beş ayrı katmanda ele alın. Her katman, isteğin bir sonraki aşamaya geçip geçemeyeceğini belirler. Özellikle bozuk JSON ile geçerli JSON içindeki eksik alanı aynı problem gibi değerlendirmemek gerekir: İlkinde sunucu veri yapısını okuyamaz, ikincisinde ise okunabilir bir veri yapısında beklenen bilgi bulunmaz.

İlk iki katmanda sorun, isteğin teknik olarak okunabilir olmamasıdır. Örneğin şu gövde geçerli bir JSON değildir:

{
  "name": "Ada",
  "email": "[email protected]"

Kapanış süslü parantezi eksik olduğu için sunucu name veya email alanlarını güvenilir biçimde değerlendiremez. Burada alan doğrulamasına geçmeden 400 döndürmek daha anlamlıdır.

Geçerli JSON içinde alanın eksik olması ise farklıdır:

{
  "name": "Ada"
}

Bu gövde parse edilebilir; ancak kayıt oluşturma sözleşmesi email alanını zorunlu tutuyorsa istek alan doğrulamasında durur. Aynı şekilde "age": "18" gibi bir değer JSON açısından geçerli olsa da API sözleşmesi sayısal değer bekliyorsa alan tipi doğrulaması başarısız olur.

Bu katmanlı yaklaşım hata gövdesini de daha kullanışlı kılar. İstemciye yalnızca “geçersiz istek” demek yerine, hatanın json, email veya business_rule katmanında olduğunu ve nasıl düzeltileceğini bildirin. Böylece istemci geliştiricisi hatayı tahmin etmek zorunda kalmaz; hangi veriyi değiştirerek isteği yeniden göndereceğini anlayabilir.

HTTP 400 ve 422 Seçimini Karar Ağacıyla Teşhis Edin

400 mü 422 mi? Önce hatanın isteğin hangi katmanında oluştuğunu bulun. İstek HTTP olarak okunamıyor, gövde çözümlenemiyor veya JSON sözdizimi bozuksa 400 düşünülür. İçerik doğru biçimde okunuyor ancak alanlar ya da iş kuralları nedeniyle işlem yapılamıyorsa 422 tercih edilebilir. Bununla birlikte bu ayrım her framework’te aynı varsayılan davranışla uygulanmaz; ekip sözleşmesi, API dokümantasyonu ve istemcinin beklediği davranış birlikte değerlendirilmelidir.

RFC 9110 HTTP Semantics, 400’ü istemci hatası nedeniyle isteğin işlenememesi; 422’yi ise içerik türü ve sözdizimi anlaşılır olduğu hâlde içeriğin işlenememesi bağlamında tanımlar. Bu nedenle kararın temel ölçütü, “sunucu isteği ne kadar ileri aşamaya kadar anlayabildi?” sorusudur.

1. HTTP isteği okunuyor mu? Metot, URL, header satırları veya istek yapısı okunamıyorsa 400 düşünün. Logda kimlik bilgileri ve hassas gövde içeriği yerine istek kimliği, endpoint ve parser hatası tutulmalıdır.
2. Content-Type ve gövde parse ediliyor mu? Sunucu beklenen medya türünü anlayamıyor ya da gövdeyi çözemiyorsa 400 gündeme gelir. Content-Type desteklenmiyorsa ekip sözleşmesine göre 415 de kullanılabilir; bu iki kodu birbirinin yerine rastgele seçmeyin.
3. JSON yapısı geçerli mi? Kapanmayan tırnak, eksik virgül veya bozuk dizi nesne yapısı 400 için güçlü kanıttır. Logda parse konumu ve güvenli bir hata kodu bulunmalıdır.
4. Alan tipi doğru mu? Örneğin age alanına sayı yerine metin geldiyse API isteği JSON olarak okuyabilir, fakat sözleşmedeki alan tipini karşılamaz. Bazı ekipler bunu 400, bazıları 422 olarak sınıflandırır.
5. Zorunlu alan mevcut mu? email gibi zorunlu bir alan yoksa istemci isteği düzelterek yeniden göndermelidir. Yanıt kodu, alanın hangi katmanda doğrulandığına göre 400 veya 422 olabilir.
6. Değer ve iş kuralı geçerli mi? E-posta biçimi doğru olsa bile kullanıcı adı zaten kullanılıyor olabilir. İstek anlaşılır olduğu hâlde işlem yapılamıyorsa 422 daha açıklayıcıdır; ancak çakışma türü durumlarda ekip 409 sözleşmesini de seçebilir.

Bu akışı kopyalanabilir bir kontrol listesine dönüştürürsek: HTTP biçimi → JSON yapısı → alan tipi → zorunlu alan → iş kuralı. Her adımda hem status code hem de istemcinin hatayı düzeltebilmesi için makinece işlenebilir bir code alanı üretin. 401, 403, 404 ve 500 gibi kodlar bu teşhis ağacının kapsamı dışındaki kimlik, yetki, kaynak ve sunucu hatalarıdır.

Kayıt Oluşturma Endpoint'inde 400 ve 422 Yanıtlarını Uygulayın

Aşağıdaki POST /users örneğinde amaç, üretim framework’ü seçmek değil, kayıt isteğinin hangi aşamada reddedileceğini görünür kılmaktır. İstemci, code ve field alanlarını kullanarak kullanıcıya mesaj gösterebilir veya form alanını doğrudan işaretleyebilir. Bu yaklaşımı kendi hızında pekiştirmek isteyenler, video yazılım eğitimleri ile benzer doğrulama akışlarını tekrar edebilir.

1. Bozuk JSON

POST /users
Content-Type: application/json

{"email": "[email protected]", "age": 20

{
  "error": {
    "code": "invalid_json",
    "message": "JSON gövdesi çözümlenemedi."
  }
}

Beklenen seçim genellikle 400 olur. İstemci JSON’u yeniden serileştirip isteği tekrar göndermelidir. Bazı API sözleşmeleri tüm gövde doğrulama hatalarını 422 altında birleştirebilir.

2. Eksik zorunlu alan

{
  "age": 20
}

{
  "error": {
    "code": "required_field",
    "field": "email",
    "message": "email alanı zorunludur."
  }
}

JSON geçerli olduğu için 422 anlamlı bir seçimdir; ancak alan şeması HTTP katmanında uygulanıyorsa ekip 400 kullanabilir. İstemci eksik alanı doldurup yeniden denemelidir.

3. Hatalı veri tipi ve 4. Geçersiz iş kuralı

{
  "email": "[email protected]",
  "age": "yirmi"
}

{
  "error": {
    "code": "invalid_type",
    "field": "age",
    "expected": "integer"
  }
}

Tip hatası için 400 veya 422 seçilebilir. E-posta doğru, fakat yaş gibi iş kuralına aykırı bir değer geldiyse örneğin 15 yaş sınırı olan bir sistemde 422 daha açıklayıcıdır:

{
  "error": {
    "code": "age_not_allowed",
    "field": "age",
    "message": "Kayıt için yaş koşulu karşılanmıyor."
  }
}

import json

def validate_user(raw):
    try:
        data = json.loads(raw)
    except json.JSONDecodeError:
        return 400, {"code": "invalid_json"}
    if "email" not in data:
        return 422, {"code": "required_field", "field": "email"}
    if not isinstance(data.get("age"), int):
        return 422, {"code": "invalid_type", "field": "age"}
    if data["age"] < 18:
        return 422, {"code": "age_not_allowed"}
    return 201, {"message": "created"}

print(validate_user('{"email":"[email protected]","age":20}'))

Beklenen çıktı: (201, {'message': 'created'}). Üretimde buna benzersiz istek kimliği, güvenli loglama ve ekipçe kararlaştırılmış hata şeması eklenmelidir.

İstemci Doğrulaması, Sunucu Doğrulaması ve Hata Yanıtı Tasarımı

İstemci tarafındaki doğrulama, kullanıcıya hızlı geri bildirim vermek için yapılır; sunucu tarafındaki doğrulama ise isteğin gerçekten kabul edilip edilmeyeceğine karar verir. Bu nedenle formun tarayıcıda kontrol edilmiş olması, API’nin gelen isteği yeniden inceleme sorumluluğunu ortadan kaldırmaz. İstemci deneyimi hızlı olmalı, sunucu kararı güvenilir olmalıdır.

Örneğin bir kayıt formu, e-posta alanının boş bırakılmasını tarayıcıda anında gösterebilir. Ancak aynı istek başka bir istemciden, doğrudan HTTP aracıyla veya kötü yapılandırılmış bir mobil uygulamadan da gelebilir. Bu yüzden API; JSON gövdesini ayrıştırmalı, alanları doğrulamalı, iş kurallarını uygulamalı ve veritabanına yazmadan önce son kontrolü kendisi yapmalıdır.

Bu katmanların aynı kontrolü içermesi çelişki değildir. İki tarafın amacı farklıdır:

• İstemci doğrulaması: Kullanıcı deneyimini iyileştirir, hatayı form alanına yakın gösterir ve gereksiz ağ isteğini azaltır.
• Sunucu doğrulaması: Her isteği bağımsız değerlendirir, güvenilir olmayan istemci verisini sınırlar ve sistemin bütünlüğünü korur.
• İş kuralı kontrolü: Kullanıcının hesabı aktif mi, aynı e-posta daha önce kullanılmış mı veya istenen işlem mevcut durumla uyumlu mu gibi uygulamaya özgü kararları verir.

İstemci tarafında temel alan kontrolleri bulunabilir; fakat bu kontroller API sözleşmesinin yerine geçmez. Kullanıcı kendi temelini ölçmek isterse ücretsiz kodlama bilgisi testi ile HTTP, JSON ve programlama temellerini gözden geçirebilir.

Hata yanıtı istemciye ne anlatmalıdır?

Hata gövdesi, istemcinin problemi anlayıp uygun bir işlem yapmasına yetecek kadar açık olmalıdır. Bunun için her endpoint’in farklı biçimde hata döndürmesi yerine ortak bir şema tercih edilebilir.

Alan bazlı hatalarda her problem ayrı bir nesne olarak döndürülebilir. Böylece istemci, kullanıcıya hangi alanların düzeltilmesi gerektiğini gösterebilir:

{
  "status": 422,
  "code": "VALIDATION_ERROR",
  "message": "İstek doğrulanamadı.",
  "errors": [
    {"field": "email", "code": "INVALID_FORMAT", "message": "Geçerli bir e-posta girin."},
    {"field": "age", "code": "MUST_BE_POSITIVE", "message": "Yaş sıfırdan büyük olmalıdır."}
  ],
  "request_id": "req_8f21c"
}

Bozuk JSON gibi sunucunun gövdeyi beklenen biçimde okuyamadığı durumlarda alan bilgisi bulunmayabilir:

{
  "status": 400,
  "code": "MALFORMED_JSON",
  "message": "İstek gövdesi geçerli bir JSON değil.",
  "request_id": "req_91ad2"
}

İstemciye iç stack trace, SQL sorgusu, tablo adı, veritabanı hata metni, sunucu dosya yolu veya kullanılan altyapının gereksiz ayrıntıları gönderilmemelidir. Bu bilgiler çoğu zaman istemcinin hatayı düzeltmesine yardımcı olmaz. İstemcinin ihtiyacı olan şey; hatanın hangi alanla ilişkili olduğu, tekrar gönderimden önce neyin değiştirilmesi gerektiği ve destek ekibiyle iletişim kurulacaksa hangi request_id değerinin paylaşılacağıdır.

Sunucu logları için uygulanabilir kontrol listesi

İstemci yanıtı kısa ve güvenli tutulurken sunucu logları teşhis için daha fazla bağlam içerebilir. Ancak log, gelen isteğin tamamını sınırsız biçimde kopyalamak anlamına gelmez. Aşağıdaki başlıklar çoğu doğrulama hatasını incelemek için yeterli bir başlangıç sağlar:

• Olayın zamanı ve mümkünse saat dilimi bilgisi
• Endpoint yolu ve HTTP metodu
• Correlation ID veya request ID
• Hatanın oluştuğu doğrulama katmanı: JSON ayrıştırma, şema, tip, zorunlu alan veya iş kuralı
• HTTP status code ve uygulama hata kodu
• Hatalı alanın adı; mümkünse alanın değeri olmadan güvenli bağlam
• İstek türü, kullanıcı oturumu veya işlem bağlamı gibi teşhis için gerekli sınırlı bilgiler
• Beklenmeyen istisnelerde exception türü, stack trace ve teknik hata ayrıntısı
• İsteğin başarısız olduğu servis veya işlem adı

Örneğin bir doğrulama hatası için log kaydı şu fikri taşıyabilir:

{
  "time": "2026-08-31T10:15:22Z",
  "method": "POST",
  "endpoint": "/users",
  "request_id": "req_8f21c",
  "layer": "field_type",
  "status": 422,
  "code": "INVALID_TYPE",
  "field": "age"
}

Hassas veriler, parolalar, erişim belirteçleri, ödeme bilgileri ve gereksiz kişisel içerikler loglanmamalıdır. Buradaki amaç kapsamlı kullanıcı profili toplamak değil, hatayı yeniden üretebilmek ve ilgili isteği güvenli biçimde bulabilmektir. Gerekirse alan değeri yerine yalnızca veri türü, uzunluk veya maskelenmiş bir gösterim kaydedilebilir.

Framework Farklılıklarını ve Kapsam Sınırlarını Nasıl Yönetmelisiniz?

HTTP 400 ve 422 seçimi, standart semantiğiyle birlikte kullanılan framework’ün varsayılan davranışından etkilenebilir. Aynı JSON doğrulama hatası bir framework’te 422, başka bir framework’te 400 olarak dönebilir. Bu nedenle yalnızca tarayıcıda görülen status code’a bakmak yerine framework dokümantasyonu, API sözleşmesi ve istemcinin hata işleme kodu birlikte incelenmelidir.

Örneğin FastAPI hata yönetimi dokümantasyonu, istek doğrulama hataları için varsayılan hata işleyicilerinin bulunduğunu ve bu işleyicilerin özelleştirilebildiğini gösterir. Bu tür bir varsayılanın varlığı, ekibin bunu otomatik olarak doğru kabul etmesi gerektiği anlamına gelmez. Önce “bizim API sözleşmemizde hangi katman hangi kodu kullanıyor?” sorusu cevaplanmalıdır.

Ekip içinde tutarlılık nasıl sağlanır?

1. Hata türlerini sınıflandırın. Bozuk JSON, beklenmeyen alan tipi, eksik zorunlu alan ve geçerli biçimdeki iş kuralı ihlalini ayrı kategoriler olarak tanımlayın.
2. Tek bir karar standardı belirleyin. Örneğin sözdizimi ve gövde yapısı sorunlarında 400, doğru okunabilen fakat kurala uymayan içerikte 422 kullanabilirsiniz. Buradaki önemli nokta, seçimin ekip genelinde aynı uygulanmasıdır.
3. API sözleşmesinde örnek gövdeler yayınlayın. Her hata kodunun hangi durumda döndüğü, örnek response gövdesi ve alan hata formatı açıkça yazılmalıdır.
4. Framework varsayılanını bilinçli biçimde değerlendirin. Varsayılan davranış sözleşmenizle uyumluysa kabul edin. Uyumlu değilse merkezi bir exception handler, middleware veya hata dönüştürme katmanıyla değiştirin.
5. Otomatik testlerle yanıtı sabitleyin. Testler yalnızca status code’u değil; code, field, message ve request_id gibi alanların biçimini de kontrol etmelidir.

Özellikle farklı ekiplerin geliştirdiği servislerde bir endpoint’in eksik alan için 400, diğerinin 422 döndürmesi istemci tarafında gereksiz koşullar oluşturur. İstemci, her servisin kendine özgü davranışını tahmin etmeye çalışmak yerine ortak bir hata sözleşmesini okuyabilmelidir.

Bu makalenin ana konusu 400 ve 422 ayrımıdır. 401 kimlik doğrulama, 403 yetkilendirme, 404 kaynak bulunamaması ve 500 beklenmeyen sunucu hatası ayrı hata sınıflarıdır; burada yalnızca kapsam sınırı olarak anılmaktadır.

Sık Sorulan Sorular

Bozuk JSON için HTTP 400 mü yoksa 422 mi kullanılmalı?

Bozuk JSON, sunucunun isteği beklenen sözdizimiyle okuyamadığı bir durumdur. Bu nedenle genel yaklaşım HTTP 400 Bad Request kullanmaktır. 422 ise JSON biçimi doğru okunabildiği hâlde içeriğin işlenemediği durumlar için daha uygundur.

Eksik zorunlu alan hatası 400 mü, 422 mi olmalıdır?

Bu seçim API sözleşmesine ve framework yaklaşımına bağlıdır. JSON yapısı okunuyor, fakat örneğin email alanı bulunmuyorsa 422 tercih edilebilir. Bazı framework’ler bunu genel model doğrulama hatası kabul edip 400 döndürür. Önemli olan aynı hata türünde tutarlı davranmak ve bunu sözleşmede belgelemektir.

İstemci tarafında doğrulama yapılmışsa sunucuda tekrar doğrulama gerekir mi?

Evet. İstemci doğrulaması kullanıcı deneyimi içindir; sunucu doğrulaması ise her isteğin bağımsız ve güvenilir biçimde değerlendirilmesi içindir. İstemci kontrolleri atlanabilir, değiştirilebilir veya farklı bir istemci tarafından hiç uygulanmayabilir.

400 ve 422 seçiminde framework’ün varsayılan davranışı nasıl değerlendirilir?

Varsayılan davranış önce incelenmeli, ardından API’nin hata sözleşmesiyle karşılaştırılmalıdır. Uyumluysa kullanılabilir; uyumsuzsa merkezi hata yönetimiyle dönüştürülebilir. Her iki durumda da otomatik testler beklenen status code ve response gövdesini güvence altına almalıdır.

API hata yanıtında istemciye hangi bilgileri, sunucu loguna hangi ayrıntıları yazmak gerekir?

İstemciye status, makine tarafından işlenebilir code, anlaşılır message, ilgili field ve request_id gibi sınırlı bilgiler verilmelidir. Sunucu logunda ise endpoint, HTTP metodu, zaman, doğrulama katmanı, hata kodu ve güvenli teşhis bağlamı bulunabilir. Stack trace ve istisna ayrıntıları logda tutulabilir; ancak iç altyapı bilgileri istemciye gönderilmemelidir.

Doğru status code seçimi, tek başına bir sayı seçmekten çok API’nin katmanlarını ve hata sözleşmesini tutarlı biçimde tasarlama işidir.