422 Unprocessable Content

Penggunaan

Error 422 Unprocessable Content menandakan bahwa server memahami permintaan tersebut tetapi menemukan isinya tidak valid secara semantik. Tipe kontennya dikenali (jika tidak, error 415 Unsupported Media Type yang akan dikirim). Sintaksnya juga valid (jika tidak, error 400 Bad Request lebih tepat).

Error semacam ini terjadi ketika permintaan menyertakan blok instruksi XML sebagai body pesan, yang tersusun dengan benar dan dipahami oleh server, namun mengandung kesalahan logika yang berujung pada error di sisi server.

Catatan

Mencoba ulang permintaan 422 tanpa mengubah body permintaan akan menghasilkan error yang sama. Klien harus memperbaiki masalah validasinya terlebih dahulu. Kembalikan 422 ketika Content-Type dikenali dan sintaksnya valid, tetapi aturan bisnis atau validasi field menolak data tersebut.

Dampak SEO

Mesin pencari seperti Google tidak akan mengindeks URL dengan status respons 422 Unprocessable Content, dan sebagai konsekuensinya, URL yang pernah terindeks namun mengembalikan kode status HTTP ini akan dihapus dari hasil pencarian.

Contoh

Klien menggunakan dokumen XML untuk meminta dimulainya task #100. Dokumen XML tersebut dikenali oleh server dan benar secara sintaksis. Server tidak memiliki catatan task dengan id=100, sehingga permintaan tersebut tidak dapat diproses.

Permintaan

POST /requests HTTP/1.1
Host: example.com
Content-Type: application/xml
Content-Length: 101

<?xml version="1.0" encoding="utf-8"?>
<request>
   <id>100</id>
   <action>start</action>
</request>

Respons

HTTP/1.1 422 Unprocessable Content
Content-Type: text/html
Content-Length: 150

<html>
  <head>
    <title>Request Failed</title>
  </head>
  <body>
   <p>Task #100 is not recognized.</p>
  </body>
</html>

Cara memperbaiki

Periksa body respons terlebih dahulu. Sebagian besar API dan framework mengembalikan detail error pada tingkat field yang menjelaskan nilai mana yang gagal dan mengapa. Manfaatkan pesan-pesan tersebut untuk menunjuk masalahnya secara tepat.

Validasi body permintaan terhadap skema yang diharapkan sebelum mengirimkannya. Pemicu yang umum mencakup field wajib yang hilang, tipe data yang keliru (mengirim string padahal API mengharapkan angka), format email atau tanggal yang tidak valid, nilai unik yang terduplikasi, dan nilai enum di luar himpunan yang diizinkan.

Pastikan header Content-Type cocok dengan format body-nya. Mengirim JSON dengan tipe konten text/plain menyebabkan kegagalan parsing di banyak server.

Pada Laravel, 422 biasanya berarti aturan validasi form tidak terpenuhi. Periksa objek errors di respons JSON untuk mengetahui nama field yang gagal beserta pesan validasinya. Pada Rails, validasi model yang gagal saat create atau update secara bawaan mengembalikan 422. Tinjau model.errors untuk rinciannya.

Untuk REST API seperti GitHub atau Shopify, pastikan payload permintaan sesuai dengan versi API yang berlaku. Nama field, parameter wajib, dan nilai yang diterima berubah antarversi.

Di sisi server, kembalikan respons error terstruktur yang mendaftar setiap field yang tidak valid, nilai yang ditolak, dan format yang diharapkan. Pesan generik “validation failed” memaksa klien menebak-nebak.

Referensi kode

.NET

HttpStatusCode.UnprocessableEntity

Rust

http::StatusCode::UNPROCESSABLE_ENTITY

Rails

:unprocessable_entity

http.StatusUnprocessableEntity

Symfony

Response::HTTP_UNPROCESSABLE_ENTITY

Python3.5+

http.HTTPStatus.UNPROCESSABLE_ENTITY

Apache HttpComponents Core

org.apache.hc.core5.http.HttpStatus.SC_UNPROCESSABLE_CONTENT
// deprecated alias: SC_UNPROCESSABLE_ENTITY

Angular

@angular/common/http/HttpStatusCode.UnprocessableEntity