422 Unprocessable Entity: Ne Anlama Gelir, Nasıl Düzeltilir

422 Unprocessable Entity ne anlama gelir

422, WebDAV'da (RFC 4918) ortaya çıktı ve sonra REST API'leri tarafından semantik doğrulama başarısızlıkları için standart yanıt olarak geniş çapta benimsendi. RFC 9110, durum metnini resmi olarak 422 Unprocessable Content olarak yeniden adlandırdı, WebDAV'a özgü "Entity" ifadesini bıraktı, ancak her iki ad da aynı durum kodunu tanımlar ve "Unprocessable Entity" çatı varsayılanlarında ve API belgelerinde açık ara daha yaygın etikettir. Önemli olan ayrım sözdizimi ile anlam arasındadır: JSON doğru ayrıştırıldı, her gerekli alan türü eşleşiyor, ve istek her yapısal kurala göre iyi biçimlendirilmiş, ama içindeki bir değer bir iş kuralını ihlal ediyor, örneğin yanlış biçimde bir e-posta adresi, gelecek bir tarih gerektiğinde geçmişteki bir tarih, veya var olmayan bir kayda başvuran bir alan.

Hata nasıl görünür

Bir 422, ezici bir şekilde bir bağlantı veya form gönderiminin doğrudan tetiklediği bir şey yerine bir API yanıtı olduğundan, neredeyse hiçbir zaman bir tarayıcı gezinme hatası olarak görünmez; bir ağ sekmesinde, bir hata bildiriminde, veya başarısız bir test iddiasında görünür. Komut satırından, yanıtın gövdesi yararlı ayrıntının yaşadığı yerdir:

curl -i -X POST https://api.example.com/v1/users   -H "Content-Type: application/json"   -d '{"email": "not-an-email", "age": -5}'

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{"errors": {"email": ["is not a valid email"], "age": ["must be greater than 0"]}}

İyi kurulmuş çoğu API, çağıranın durum kodundan tahmin etmesini bırakmak yerine, tam olarak hangi alanın başarısız olduğunu ve nedenini adlandıran, 422 yanında yapılandırılmış bir hata gövdesi döndürür.

422 Unprocessable Entity'ye ne sebep olur

• REST API'lerinde doğrulama hataları. Rails uygulamaları, bir ActiveRecord modeli oluşturma veya güncellemede doğrulamayı başarısız kıldığında yaygın olarak otomatik olarak 422 döndürür. Laravel'in form isteği doğrulaması, başarısız kurallar için varsayılan olarak 422 döndürür. Pydantic üzerine kurulu FastAPI, istek verisi bir Pydantic modelinin tür veya kısıtlama kontrollerini her başarısız kıldığında 422 döndürür, ki bu yüzden özellikle FastAPI projelerinde en sık görülen durum kodlarından biridir.
• Doğru türe ama geçersiz bir değere sahip bir alan. Bir dize beklendiği yerde bir dize, ama bir biçim kontrolünü, bir uzunluk sınırını, veya izin verilen değerler listesini başarısız kılan bir tane.
• Var olmayan bir şeye başvuru. İstek gövdesindeki, sözdizimsel olarak iyi durumda ama herhangi bir gerçek kayda karşılık gelmeyen bir yabancı anahtar, kullanıcı kimliği, veya slug.
• Basit alan doğrulamasının ötesindeki iş kuralları. Sözdizimsel olarak geçerli ama süresi dolmuş bir indirim kodu, veya geçerli bir tam sayı ama mevcut stoku aşan bir miktar.
• Gerekli bir alanın tamamen eksik olması. Çatıya bağlı olarak, eksik gerekli bir alan, 400 yerine 422 döndürebilir, çünkü istek gayet iyi ayrıştırılır, sadece doğrulama katmanının gerektirdiği bir değerden yoksundur.

422'ye karşı 400

Çizgi sözdizimi ile anlam arasındadır. 400 Bad Request, sunucunun isteği hiç ayrıştıramadığı anlamına gelir, örneğin bozuk JSON veya herhangi bir yapısal kurala göre geçerli olmayan bir gövde. 422, isteğin hiçbir sorun olmadan ayrıştığı, ve her alanın doğru türde olduğu, ama içindeki bir değerin ayrıştırma sonrası uygulamanın kontrol ettiği bir kuralı başarısız kıldığı anlamına gelir. Pratikte birçok API bu ayrımı bulanıklaştırır ve her iki durum için de 400 kullanır, ki bu savunulabilir ama daha az kesindir; bir API'ye entegre olan bir istemci, sadece durum koduna güvenmek yerine tam olarak neyin başarısız olduğunu bilmek için yanıt gövdesini okumalıdır.

422 hatası nasıl düzeltilir

Bir API çağıran bir istemciyseniz

1. Sadece durum kodunu değil yanıt gövdesini okuyun. İyi kurulmuş bir API'nin 422 yanıtı, başka bir tahmine gerek kalmadan tam olarak neyi düzeltmeniz gerektiğini söyleyen, başarısız olan belirli alanı ve kuralı adlandırır.
2. Alanı, biçim, uzunluk ve izin verilen değerler gibi API'nin belgelenmiş kısıtlamalarına karşı kontrol edin, çünkü bunlar şema tek başına size göstermeyeceği iş kurallarıdır.
3. 422'yi veriyi düzeltmek için bir sinyal olarak ele alın, isteği değiştirmeden yeniden denemek için değil. Doğrulaması başarısız olan değiştirilmemiş bir isteği yeniden denemek her seferinde aynı şekilde başarısız olacaktır; iyi davranan bir istemci, sessizce yeniden denemek yerine belirli hatayı kullanıcıya yüzeye çıkarmalıdır.

API'yi çalıştırıyorsanız

1. 422 yanında her zaman, açıklama olmadan çıplak bir durum kodu yerine, başarısız olan alanı ve kuralı adlandıran yapılandırılmış bir hata gövdesi döndürün.
2. Doğrulama hata mesajlarını spesifik ve eyleme geçirilebilir tutun, örneğin, çağıranı birkaç alandan hangisinin sorun olduğunu tahmin etmeye zorlayan genel bir "validation failed" yerine "email must be a valid address."
3. API'niz için 400 ile 422 arasında kasıtlı olarak karar verin ve seçimi belgeleyin, böylece entegratörler her 4xx'i aynı şekilde ele almak yerine güvenilir hata işleme kurabilir.
4. Kendi istemci kodunuzun API'nin gerçek kurallarını sürekli başarısız kılan veri gönderdiği durumları yakalamak için, geliştirme sırasında doğrulanmış-ama-reddedilmiş yükleri günlüğe kaydedin, ki bu genellikle istemci ile API'nin gerçek kuralları arasında bir uyuşmazlığa işaret eder.

Bir istemci bir 422 yanıtını nasıl ele almalı

İyi tasarlanmış bir istemci, 422'yi bir 5xx hatasından veya bir ağ başarısızlığından temelde farklı ele alır: sunucunun sağlıklı olduğu ve doğru çalıştığı, ve çağıranın sunucunun olduğu gibi asla kabul etmeyeceği bir şey gönderdiği anlamına gelir. Doğru yanıt, hata gövdesini ayrıştırmak, her başarısız alanı onu üreten form veya girdiyle eşlemek, ve kullanıcıya eyleme geçirilebilir bir şey göstermektir, bir zaman aşımı veya bir 503 için yapacağınız gibi geri çekilmeyle yeniden denemek değil. Bir API'nin doğrulama katmanını çalıştıran otomatik testler, sadece 422 durum kodunda değil, döndürülen belirli hata gövdesinde iddia etmelidir, çünkü doğrulama mantığının kendisinin doğru olduğunu onaylayan budur.

422'lerin fark edilmeden kalması nasıl önlenir

Bir dağıtımdan, üçüncü taraf bir kütüphane güncellemesinden, veya bir şema geçişinden olsun, beklenmedik şekilde değişen bir doğrulama kuralı, önceden başarılı olan istekleri sessizce reddetmeye başlayabilir. Bilinen iyi bir yük gönderen ve beklenen durum kodu üzerinde iddia eden bir HTTP kontrolü, bu tür bir gerilemeyi bir dağıtımdan hemen sonra yakalar. Sadece durum kodunun tam olarak doğrulayamadığı birden fazla uç noktalı veya bir yüke sahip API'ler için, yanıt gövdesini de kontrol eden API izlemesi, sunucunun sadece erişilebilir olduğunu değil, doğrulama mantığının kendisini de doğrular.

İlgili hatalar

Bu kılavuzun karşılaştırdığı isteğin-ayrıştırılamadığı durum için 400 Bad Request'e, daha geniş aile için 4xx genel bakışına, ve bu partide başka yerde 401 Unauthorized ve 405 Method Not Allowed'a bakın.

Sık sorulan sorular

422 Unprocessable Entity, 422 Unprocessable Content ile aynı mı?

Evet. RFC 9110, neden ifadesini Unprocessable Content olarak yeniden adlandırdı, ama aynı anlama sahip aynı durum kodudur; çoğu çatı ve API belgesi hâlâ eski Unprocessable Entity ifadesini kullanır.

FastAPI uygulamam eksik bir alan için neden 422 döndürüyor?

FastAPI, istek verisini otomatik olarak Pydantic modellerinize karşı doğrular, ve eksik gerekli bir alan, veya yanlış türde bir tane, o doğrulamayı başarısız kılar ve tam olarak hangi alanın ve kuralın başarısız olduğunu tanımlayan bir gövdeyle 422 döndürür.

422 alan bir isteği yeniden denemeli miyim?

Sadece doğrulamayı başarısız kılan veriyi değiştirdikten sonra. Aynı isteği yeniden denemek her seferinde aynı 422'yi üretecektir, çünkü sunucu aynı geçersiz girdiyi doğru ve tutarlı bir şekilde reddediyor.

Pratikte 422 ile 400 arasındaki fark nedir?

400, sunucunun hiç ayrıştıramadığı bir istek içindir. 422, gayet iyi ayrıştıran ama bir doğrulama veya iş kuralını başarısız kılan bir değer içeren bir istek içindir. Birçok gerçek dünya API'si her ikisi için de 400 kullanır, bu yüzden aradığınız belirli API için belgelenmiş kuralı her zaman kontrol edin.

Bir 422, sunucunun bir hatası olduğu anlamına gelebilir mi?

Doğrulama kuralının kendisi yanlışsa olabilir, örneğin gerçekten geçerli bir e-posta biçimini reddetmek. Ama bir 422 tasarım gereği sunucunun amaçlandığı gibi çalıştığı ve veriye itiraz ettiği anlamına gelir, bu yüzden bozuk olduğunu varsaymadan önce gerçek doğrulama kuralını araştırın.