422 Unprocessable Content

Uso

El error 422 Unprocessable Content indica que el servidor comprende la solicitud, pero considera que su contenido no es válido desde el punto de vista semántico. El tipo de contenido se reconoce (de lo contrario se enviaría un error 415 Unsupported Media Type). La sintaxis también es válida (de lo contrario resultaría más apropiado un error 400 Bad Request).

Un error de este tipo se produce cuando la solicitud incluye un bloque de instrucciones XML como cuerpo del mensaje, bien formado y comprendido por el servidor, pero que contiene errores de lógica que provocan un error en el lado del servidor.

Nota

Reintentar un 422 sin modificar el cuerpo de la solicitud produce el mismo error. El cliente debe corregir primero el problema de validación. Devuelva 422 cuando el Content-Type se reconozca y la sintaxis sea válida, pero las reglas de negocio o la validación de campos rechacen los datos.

Impacto en SEO

Los buscadores como Google no indexan una URL con el estado de respuesta 422 Unprocessable Content y, en consecuencia, las URL indexadas en el pasado que devuelvan este código de estado HTTP se eliminarán de los resultados de búsqueda.

Ejemplo

El cliente utiliza un documento XML para solicitar el inicio de la tarea n.º 100. El servidor reconoce el documento XML y su sintaxis es correcta. El servidor no tiene registro de una tarea con id=100, por lo que la solicitud no se puede procesar.

Solicitud

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>

Respuesta

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>

Cómo solucionarlo

Inspeccione primero el cuerpo de la respuesta. La mayoría de las API y los frameworks devuelven detalles de error a nivel de campo que explican qué valor falló y por qué. Use esos mensajes para localizar el problema exacto.

Valide el cuerpo de la solicitud frente al esquema esperado antes de enviarlo. Entre los desencadenantes habituales están la falta de campos obligatorios, los tipos de datos incorrectos (enviar una cadena donde la API espera un número), los formatos de correo electrónico o de fecha no válidos, los valores únicos duplicados y los valores de enumeración fuera del conjunto permitido.

Confirme que la cabecera Content-Type coincide con el formato del cuerpo. Enviar JSON con el tipo de contenido text/plain provoca fallos de análisis en muchos servidores.

En Laravel, un 422 suele significar que no se cumplieron las reglas de validación del formulario. Revise el objeto errors de la respuesta JSON para ver los nombres de los campos que fallaron y los mensajes de validación. En Rails, las validaciones de modelo fallidas al crear o actualizar devuelven 422 de forma predeterminada. Inspeccione model.errors para conocer los detalles.

En las API REST como las de GitHub o Shopify, verifique que la carga útil de la solicitud se corresponde con la versión actual de la API. Los nombres de los campos, los parámetros obligatorios y los valores aceptados cambian de una versión a otra.

En el lado del servidor, devuelva respuestas de error estructuradas que enumeren cada campo no válido, el valor rechazado y el formato esperado. Los mensajes genéricos de tipo “validation failed” obligan al cliente a adivinar.

Referencias de código

.NET

HttpStatusCode.UnprocessableEntity

Rust

http::StatusCode::UNPROCESSABLE_ENTITY

Rails

:unprocessable_entity

Go

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