Blog

422 Durum Kodu: İşlenemeyen Varlık Nedir? Anlamsal Doğrulayıcı

INEZA Felin-Michel

INEZA Felin-Michel

16 October 2025

422 Durum Kodu: İşlenemeyen Varlık Nedir? Anlamsal Doğrulayıcı

Bir web sitesinde kayıt formu dolduruyorsunuz. E-posta adresinizi giriyorsunuz, ancak tanıdık format yerine yanlışlıkla "john@company" yazıyorsunuz. Gönder'e tıklıyorsunuz ve genel bir "Bir şeyler ters gitti" mesajı yerine, net, spesifik bir hata alıyorsunuz: "Lütfen geçerli bir e-posta adresi girin." Sunucu isteğinizi mükemmel bir şekilde anladı, sadece anlamsal olarak bir anlam ifade etmiyordu.

İşte bu hassas, kullanıcı dostu hata işleme, tam da 422 Unprocessable Entity HTTP durum kodunun tasarlandığı şeydir. Bu, 400 Bad Request hatasının daha gelişmiş bir kuzenidir ve isteğin yapısal olarak doğru ancak anlamsal olarak anlamsız olduğu durumlar için tasarlanmıştır.

Basit görünen ama "Tam olarak neyi yanlış yaptım?" diye merak etmenize neden olabilen o sinir bozucu hatalardan biridir.

Doğru yerdesiniz. Bu yazıda, HTTP durum kodu 422'nin aslında ne anlama geldiğini, neden oluştuğunu, nasıl düzeltileceğini ve Apidog gibi güçlü bir API test aracı kullanarak nasıl kolayca hata ayıklayabileceğinizi açıklayacağız.

Bunu, anlamsız ama dilbilgisel olarak mükemmel bir cümle yazmakla ("Renksiz yeşil fikirler öfkeyle uyur") dilbilgisi bozuk bir cümle yazmak arasındaki fark gibi düşünebilirsiniz ("Öfkeyle uyur yeşil fikirler renksiz"). 422 hatası ilk senaryo içindir; sözdizimi iyi, ancak anlam bozuk.

Modern API'lar geliştiriyor veya kullanıyorsanız, özellikle karmaşık veri doğrulama işlemleri yapanlar için, 422'yi anlamak, harika geliştirici ve kullanıcı deneyimleri oluşturmak için çok önemlidir.

💡
Sağlam doğrulamaya ihtiyaç duyan API'lar geliştiriyorsanız, bu özel hata senaryolarını test etmenize yardımcı olabilecek bir araca ihtiyacınız var. Apidog'u ücretsiz indirin; bu, 422 yanıtlarını tetikleyen istekleri oluşturmayı ve doğrulama mantığınızın doğru çalıştığını doğrulamayı kolaylaştıran hepsi bir arada bir API geliştirme platformudur.

Şimdi, HTTP 422 İşlenemeyen Varlık durum kodunun amacını, gücünü ve pratik uygulamasını inceleyelim.

Sorun: "Hatalı İstek" Yeterince Spesifik Olmadığında

422'nin neden var olduğunu anlamak için, öncülü olan 400 Bad Request hatasının sınırlamalarına bakmamız gerekiyor.

400 durum kodu, istemci hataları için genel bir kod olarak kullanılır. Şu anlamlara gelebilir:

Bu belirsizlik, API tüketicileri için sorunlar yaratır. Bir 400 hatası alırsanız, JSON sözdiziminizi mi düzeltmeniz gerektiğini yoksa gönderdiğiniz verilerde bir sorun mu olduğunu bilemezsiniz.

422 durum kodu, sözdizimsel hatalar ile anlamsal doğrulama hataları arasında net bir ayrım yaparak bu belirsizliği çözmek için tanıtıldı.

HTTP 422 İşlenemeyen Varlık Aslında Ne Anlama Geliyor?

422 Unprocessable Entity durum kodu, sunucunun istek varlığının içerik türünü anladığını ve istek varlığının sözdiziminin doğru olduğunu, ancak içerdiği talimatları işleyemediğini gösterir.

Basit bir ifadeyle, HTTP 422 İşlenemeyen Varlık, sunucunun isteğinizi anladığı ancak anlamsal veya doğrulama hataları nedeniyle işleyemediği anlamına gelir.

Ana fikir şudur: İstek iyi biçimlendirilmiş, ancak sunucunun onu işlemesini engelleyen anlamsal hatalar içeriyor.

İşte nasıl çalıştığı:

400 veya 500 döndürmek yerine, bir 422 döndürür.

Bu durum kodu başlangıçta RFC 4918 (WebDAV)'de tanımlanmıştır, ancak günümüzde REST API'larında ve modern web uygulamalarında isteklerdeki doğrulama hatalarını veya anlamsal hataları belirtmek için yaygın olarak kullanılmaktadır.

Tipik bir 422 yanıtı şöyle görünür:

HTTP/1.1 422 Unprocessable EntityContent-Type: application/json
{
  "error": "Validation failed",
  "details": [
    {
      "field": "email",
      "message": "Must be a valid email address"
    },
    {
      "field": "age",
      "message": "Must be at least 18 years old"
    }
  ]
}

Resmi Tanım (RFC 4918'e Göre)

RFC dokümantasyonuna göre:

"422 (İşlenemeyen Varlık) durum kodu, sunucunun istek varlığının içerik türünü anladığı ve istek varlığının sözdiziminin doğru olduğu, ancak içerdiği talimatları işleyemediği anlamına gelir."

Daha basit bir ifadeyle:

422 Yanıtının Anatomisi

422 yanıtlarını bu kadar kullanışlı kılan şey yapılarıdır. Genel 400 hatalarından farklı olarak, 422 yanıtları genellikle neyin yanlış gittiği hakkında ayrıntılı bilgi içerir.

İyi Yapılandırılmış Bir 422 Yanıtı Şunları İçerir:

  1. Net Hata Mesajı: Sorunun üst düzey açıklaması
  2. Alana Özel Hatalar: Hangi belirli alanların doğrulamadan geçemediği
  3. Ayrıntılı Mesajlar: Her doğrulama hatası için insan tarafından okunabilir açıklamalar
  4. Hata Kodları: Programatik işleme için makine tarafından okunabilir kodlar
  5. Potansiyel Değerler: Bazen önerilen geçerli değerler

Bu yapı, istemci tarafında çok daha iyi hata işleme sağlar.

Gerçek Dünya Örnekleri: 422 Ne Zaman Kullanılır

422'nin mükemmel bir seçim olduğu bazı somut senaryolara bakalım.

Örnek 1: Kullanıcı Kaydı

İstek:

POST /api/users
{
  "email": "not-an-email",
  "password": "123",
  "birth_date": "2025-01-01"
}

Yanıt:

HTTP/1.1 422 Unprocessable Entity
{
  "error": "Validation failed",
  "details": [
    {
      "field": "email",
      "message": "Must be a valid email address",
      "code": "INVALID_EMAIL"
    },
    {
      "field": "password",
      "message": "Password must be at least 8 characters",
      "code": "PASSWORD_TOO_SHORT"
    },
    {
      "field": "birth_date",
      "message": "Birth date cannot be in the future",
      "code": "FUTURE_BIRTH_DATE"
    }
  ]
}

Örnek 2: E-ticaret Siparişi

İstek:

POST /api/orders
{
  "product_id": "prod_123",
  "quantity": -5,
  "shipping_method": "express_moon_delivery"
}

Yanıt:

HTTP/1.1 422 Unprocessable Entity
{
  "error": "Order validation failed",
  "details": [
    {
      "field": "quantity",
      "message": "Quantity must be positive",
      "code": "INVALID_QUANTITY"
    },
    {
      "field": "shipping_method",
      "message": "Unsupported shipping method",
      "code": "INVALID_SHIPPING_METHOD",
      "allowed_values": ["standard", "express", "overnight"]
    }
  ]
}

422 ve 400: Kritik Ayrım

Bu, API tasarımcıları ve tüketicileri için en önemli karşılaştırmadır.

Senaryo Doğru Durum Kodu Neden
Bozuk JSON: {"email": "test@example.com",} (sondaki virgül) 400 Bad Request Sözdizimi hatası - JSON ayrıştırıcısı bunu anlayamaz
Geçersiz veriye sahip geçerli JSON: {"email": "not-an-email"} 422 Unprocessable Entity Anlamsal hata - JSON mükemmel, ancak e-posta formatı geçersiz
Aksi takdirde geçerli JSON'da eksik gerekli alan 422 Unprocessable Entity Anlamsal hata - yapı doğru, ancak gerekli veriler eksik
Yanlış Content-Type başlığı 400 Bad Request Sözdizimi hatası - sunucu gövdeyi nasıl ayrıştıracağını bilmiyor

Basit Kural:

HTTP 422 Hatalarının Yaygın Nedenleri

Ne anlama geldiğini bildiğinize göre, bir 422 İşlenemeyen Varlık yanıtının arkasındaki olağan şüphelilere bakalım.

1. Doğrulama Başarısızlıkları

Bu en yaygın nedendir.

API'niz doğrulama kuralları kullanıyorsa (örneğin, Laravel, Django veya Express gibi çerçeveler aracılığıyla) ve girdiniz bunları ihlal ediyorsa, bir 422 görürsünüz.

Örnek:

2. Anlamsal Hatalar

Veri formatı geçerli olsa bile, anlamı geçerli olmayabilir.

Örneğin, "başlangıç tarihi"nin "bitiş tarihi"nden sonra olduğu bir gönderim.

3. Desteklenmeyen Veri Tipleri

İstek gövdeniz sunucunun desteklemediği bir içerik türü kullanıyorsa (örneğin, sunucu JSON beklerken XML göndermek), sunucu bir 422 ile yanıt verebilir.

4. Veritabanı Kısıtlama İhlalleri

Verileriniz, yinelenen benzersiz bir alan gibi bir veritabanı kısıtlamasını ihlal ediyorsa, sunucunuz bir 422 döndürebilir.

Örnek:

5. Yanlış API Sözleşmesi

Bazen geliştiriciler API'nin tanımadığı alanları gönderir veya gerekli olanları unutur.

Sunucu bunları işleyemez, bu da bir 422 ile sonuçlanır.

422 Hatasını Düzeltme: Pratik Çözümler

İşte bir 422 İşlenemeyen Varlık hatasını düzeltmenin veya önlemenin en etkili yolları.

1. İstek Verilerini Tekrar Kontrol Edin

Tüm alanların mevcut olduğundan ve doğru biçimlendirildiğinden emin olun.

Örneğin, e-posta adreslerinin "@" içerdiğinden, telefon numaralarının yalnızca rakamlardan oluştuğundan ve tarih formatlarının beklentilerle eşleştiğinden emin olun.

2. Uygun Doğrulama Uygulayın

Veri doğruluğunu sağlamak için doğrulama kütüphaneleri veya çerçeveleri kullanın.

Node.js'de (Express + Joi) örneğin:

const Joi = require('joi');

const schema = Joi.object({
  username: Joi.string().min(3).required(),
  email: Joi.string().email().required(),
  age: Joi.number().min(0)
});

3. Hata Mesajlarını İyileştirin

Net hata yanıtları, istemcilerin isteklerini daha hızlı düzeltmelerine yardımcı olur.

Belirsiz "işlenemeyen varlık" mesajları yerine, nedenini açıklayan yapılandırılmış JSON döndürün.

4. Apidog ile Test Edin

Apidog, API çağrılarını simüle etmenize, şemaları doğrulamanıza ve doğrulama hatalarını gerçek zamanlı olarak görüntülemenize olanak tanır.

API'nizi dağıtmadan önce istekleri test etmek için hatta ortam değişkenlerini ve sahte sunucuları kullanabilirsiniz.

5. Sunucu ve İstemcinin Aynı Şemayı Kullandığından Emin Olun

OpenAPI veya Swagger kullanıyorsanız, her iki tarafın da aynı spesifikasyonu kullandığından emin olun.

Apidog, tutarlı dokümantasyon oluşturmaya ve kod tabanınızla otomatik senkronizasyona yardımcı olabilir.

REST API'lerinde 422: Neden Bu Kadar Yaygın?

422 durum kodu, pratik olarak RESTful API'ların poster çocuğudur.

Modern API'larda, özellikle en iyi uygulamaları takip edenlerde, 422 istemcilere şunu bildirmek için kullanılır:

"İsteğiniz sözdizimsel olarak geçerliydi, ancak verinin içinde bir şeyler yanlış."

Neden tercih edilir:

Rails, Laravel ve Spring Boot gibi çerçeveler, form veya JSON doğrulaması başarısız olduğunda otomatik olarak 422 döndürür.

Apidog ile 422 Yanıtlarını Test Etme

Sağlam API'lar oluşturmak için doğrulama mantığını test etmek çok önemlidir. API'nizin geçersiz verileri doğru bir şekilde tanımladığından ve yardımcı hata mesajları döndürdüğünden emin olmanız gerekir. Apidog bu iş akışı için mükemmeldir.

Apidog ile şunları yapabilirsiniz:

  1. Doğrulama Test Paketleri Oluşturun: API'nizdeki her doğrulama kuralını test eden bir istek koleksiyonu oluşturun.
  2. Uç Durumları Test Edin: Geçersiz veri türleri, aralık dışı değerler ve eksik gerekli alanlarla kolayca istekler oluşturun.
  3. Hata Yanıtlarını Doğrulayın: API'nizin anlamsal doğrulama hataları için 422 (400 değil) döndürdüğünü ve yanıt gövdesinin ayrıntılı hata bilgileri içerdiğini kontrol edin.
  4. Regresyon Testini Otomatikleştirin: Yeni kod değişikliklerinin mevcut doğrulama mantığını bozmadığından emin olmak için doğrulama testlerinizi otomatik olarak çalıştırın.
  5. Hata Mesajı Kalitesini Test Edin: Hata mesajlarının hem geliştiriciler hem de son kullanıcılar için açık ve eyleme geçirilebilir olduğunu doğrulayın.
Düğme

Bu sistematik test yaklaşımı, API'nizin işler ters gittiğinde bile harika bir deneyim sunmasını sağlar.

422 Yanıtlarını Uygulamak İçin En İyi Uygulamalar

API Geliştiricileri İçin:

Frontend Geliştiricileri İçin:

Yaygın Uygulama Kalıpları

Express.js'de (Node.js):

app.post('/api/users', (req, res) => {
  const { error, value } = userSchema.validate(req.body);

  if (error) {
    return res.status(422).json({
      error: 'Validation failed',
      details: error.details.map(detail => ({
        field: detail.path.join('.'),
        message: detail.message,
        code: detail.type
      }))
    });
  }

  // Geçerli veriyi işleyin...
});

Django REST Framework'te (Python):

class UserSerializer(serializers.ModelSerializer):
    class Meta:
        model = User
        fields = ['email', 'password', 'birth_date']

    def validate_birth_date(self, value):
        if value > timezone.now().date():
            raise serializers.ValidationError("Doğum tarihi gelecekte olamaz")
        return value

def create(self, request):
    serializer = UserSerializer(data=request.data)
    if not serializer.is_valid():
        return Response(
            {
                'error': 'Doğrulama başarısız oldu',
                'details': serializer.errors
            },
            status=status.HTTP_422_UNPROCESSABLE_ENTITY
        )
    # Geçerli veriyi kaydedin...

422 Ne Zaman Kullanılmaz

422 doğrulama hataları için harika olsa da, tüm senaryolar için uygun değildir:

Güvenlik Tarafı: 422 Neden 500'den Daha Güvenlidir

Doğrulama başarısız olduğunda neden sadece bir 500 Dahili Sunucu Hatası döndürülmediğini merak edebilirsiniz?

İşte neden olmasın:

422 kullanmak, tam olarak hangi doğrulama mesajlarının döndürüleceğini kontrol edebildiğiniz için hassas dahili ayrıntıların açığa çıkmasını da önler.

Sonuç: Daha İyi API Deneyimleri Yolu

HTTP 422 Unprocessable Entity durum kodu, API tasarımında önemli bir ilerlemeyi temsil eder. Genel 400 hatalarından çok daha yardımcı olan, doğrulama hatalarını iletmek için açık, standartlaştırılmış bir yol sağlar.

Anlamsal doğrulama hataları için 422'yi benimseyerek, şunları sağlayan API'lar oluşturursunuz:

Genel 400 hatalarından spesifik 422 yanıtlarına geçiş, API tasarım felsefesinde, kötü istekleri basitçe reddetmekten, istemcilerin hatalarını anlamalarına ve düzeltmelerine aktif olarak yardımcı olmaya doğru bir olgunlaşmayı temsil eder.

Bu nedenle, bir dahaki sefere karmaşık doğrulama kurallarına sahip bir API oluşturduğunuzda, 422 durum koduna ulaşın. Ve doğrulama mantığınızın mükemmel çalıştığını test etmeniz gerektiğinde, Apidog gibi bir araç, API'nizin başarılı yanıtlarının yanı sıra olağanüstü hata işleme sağlaması için gereken hassasiyeti ve kontrolü size verecektir. Ve bunları erken yakalamanın ve düzeltmenin en kolay yolunun kapsamlı test yapmak olduğunu unutmayın.

422'lerin API geliştirmenizi yavaşlatmasına izin vermeyin. Apidog'u ücretsiz indirin ve doğrulama sorunlarını kullanıcılarınızdan önce yakalayın.

Düğme

API Tasarım-Öncelikli Yaklaşımı Apidog'da Uygulayın

API'leri oluşturmanın ve kullanmanın daha kolay yolunu keşfedin

Ücretsiz Kaydolİndir