422 Unprocessable Entity: qué significa y cómo solucionarlo

Qué significa 422 Unprocessable Entity

El 422 se originó en WebDAV (RFC 4918) y más tarde lo adoptaron ampliamente las API REST como la respuesta estándar para fallos de validación semántica. El RFC 9110 renombró formalmente el texto de estado a 422 Unprocessable Content, eliminando el texto "Entity" específico de WebDAV, aunque ambos nombres describen el mismo código de estado idéntico y "Unprocessable Entity" sigue siendo la etiqueta con diferencia más habitual en los valores por defecto de los frameworks y en la documentación de las API. La distinción que importa es sintaxis frente a semántica: el JSON se interpretó correctamente, todos los tipos de los campos obligatorios coinciden, y la petición está bien formada según cualquier regla estructural, pero un valor de dentro incumple una regla de negocio, como una dirección de correo con el formato equivocado, una fecha en el pasado donde se exige una fecha futura, o un campo que referencia un registro que no existe.

Cómo aparece el error

Un 422 casi nunca aparece como un error de navegación del navegador, ya que es abrumadoramente una respuesta de API y no algo que dispare directamente un enlace o el envío de un formulario; aparece en una pestaña de red, en un aviso de error, o en una aserción de test fallida. Desde la línea de comandos, el cuerpo de la respuesta es donde está el detalle útil:

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"]}}

La mayoría de las API bien construidas devuelven un cuerpo de error estructurado junto al 422, nombrando exactamente qué campo falló y por qué, en lugar de dejar que quien llama lo adivine solo por el código de estado.

Qué causa un 422 Unprocessable Entity

• Errores de validación en API REST. Las aplicaciones Rails habitualmente devuelven 422 de forma automática cuando un modelo ActiveRecord falla la validación al crear o actualizar. La validación de form request de Laravel devuelve 422 por defecto para las reglas que fallan. FastAPI, construido sobre Pydantic, devuelve 422 siempre que los datos de la petición fallan las comprobaciones de tipo o de restricción de un modelo Pydantic, por lo que es uno de los códigos de estado que más se ven específicamente en proyectos FastAPI.
• Un campo con el tipo correcto pero un valor inválido. Una cadena donde se esperaba una cadena, pero una que falla una comprobación de formato, un límite de longitud, o una lista de valores permitidos.
• Una referencia a algo que no existe. Una clave foránea, un id de usuario, o un slug en el cuerpo de la petición que es sintácticamente correcto pero no corresponde a ningún registro real.
• Reglas de negocio más allá de la simple validación de campos. Un código de descuento sintácticamente válido pero caducado, o una cantidad que es un entero válido pero supera el stock disponible.
• Falta por completo un campo obligatorio. Según el framework, un campo obligatorio ausente puede devolver 422 en lugar de 400, ya que la petición se interpreta sin problema, simplemente le falta un valor que exige la capa de validación.

422 frente a 400

La línea divisoria es sintaxis frente a semántica. 400 Bad Request significa que el servidor no pudo interpretar la petición en absoluto, por ejemplo un JSON mal formado o un cuerpo que no es válido según ninguna regla estructural. 422 significa que la petición se interpretó sin ningún problema, y cada campo tiene el tipo correcto, pero un valor de dentro incumple una regla que la aplicación comprueba después de interpretarla. En la práctica, muchas API difuminan esta distinción y usan 400 para ambos casos, lo cual es defendible pero menos preciso; un cliente que integra contra una API debería leer el cuerpo de la respuesta en lugar de fiarse solo del código de estado para saber exactamente qué falló.

Cómo corregir un error 422

Si eres un cliente que llama a una API

1. Lee el cuerpo de la respuesta, no solo el código de estado. La respuesta 422 de una API bien construida nombra el campo y la regla concretos que fallaron, lo que te dice exactamente qué corregir sin tener que adivinar más.
2. Revisa el campo frente a las restricciones documentadas de la API como el formato, la longitud, y los valores permitidos, ya que estas son reglas de negocio que el esquema por sí solo no te mostrará.
3. Trata el 422 como una señal para corregir los datos, no para reintentar la petición sin cambios. Reintentar una petición idéntica que falló la validación fallará igual siempre; un cliente bien construido debería mostrar el error concreto al usuario en lugar de reintentar en silencio.

Si administras la API

1. Devuelve siempre un cuerpo de error estructurado junto al 422, nombrando el campo y la regla que fallaron, en lugar de un código de estado desnudo sin ninguna explicación.
2. Mantén los mensajes de error de validación específicos y accionables, por ejemplo "email must be a valid address" en lugar de un genérico "validation failed" que obliga a quien llama a adivinar cuál de varios campos era el problema.
3. Decide deliberadamente entre 400 y 422 para tu API y documenta la decisión, para que quienes integren puedan construir una gestión de errores fiable en lugar de tratar cada 4xx igual.
4. Registra los payloads validados-pero-rechazados durante el desarrollo para detectar casos en los que tu propio código de cliente está enviando datos que fallan la validación de forma constante, algo que a menudo apunta a un desajuste entre el cliente y las reglas reales de la API.

Cómo debería gestionar un cliente una respuesta 422

Un cliente bien diseñado trata el 422 como algo fundamentalmente distinto de un error 5xx o de un fallo de red: significa que el servidor está sano y funcionando correctamente, y que quien llama envió algo que el servidor nunca va a aceptar tal cual. La respuesta correcta es interpretar el cuerpo del error, mapear cada campo fallido de vuelta al formulario o campo que lo produjo, y mostrarle al usuario algo accionable, no reintentar con backoff como harías ante un tiempo de espera agotado o un 503. Los tests automatizados que ejercitan la capa de validación de una API deberían hacer aserciones sobre el cuerpo de error concreto devuelto, no solo sobre el código de estado 422, ya que eso es lo que confirma que la propia lógica de validación es correcta.

Cómo prevenir que los 422 pasen desapercibidos

Una regla de validación que cambió inesperadamente, ya sea por un despliegue, una actualización de una librería de terceros, o una migración de esquema, puede empezar a rechazar en silencio peticiones que antes tenían éxito. Una comprobación HTTP que envía un payload que sabes que funciona y hace una aserción sobre el código de estado esperado detecta ese tipo de regresión inmediatamente después de un despliegue. Para API con más de un endpoint o un payload que el código de estado por sí solo no puede verificar del todo, la monitorización de API que también comprueba el cuerpo de la respuesta confirma la propia lógica de validación, no solo que el servidor sea alcanzable.

Errores relacionados

Consulta 400 Bad Request para el caso de la-petición-no-se-pudo-interpretar frente al que contrasta esta guía, la guía de la familia 4xx para la familia más amplia, y 401 Unauthorized y 405 Method Not Allowed en otros sitios de esta tanda.

Preguntas frecuentes

¿Es 422 Unprocessable Entity lo mismo que 422 Unprocessable Content?

Sí. El RFC 9110 renombró la frase de motivo a Unprocessable Content, pero es el mismo código de estado con el mismo significado; la mayoría de los frameworks y la documentación de API todavía usan el texto más antiguo Unprocessable Entity.

¿Por qué mi aplicación FastAPI devuelve 422 para un campo ausente?

FastAPI valida automáticamente los datos de la petición contra tus modelos Pydantic, y un campo obligatorio ausente, o uno con el tipo equivocado, falla esa validación y devuelve 422 con un cuerpo que describe exactamente qué campo y qué regla fallaron.

¿Debería reintentar una petición que recibió un 422?

Solo después de cambiar los datos que fallaron la validación. Reintentar la petición idéntica va a producir el mismo 422 cada vez, ya que el servidor está rechazando correcta y consistentemente la misma entrada inválida.

¿Cuál es la diferencia entre 422 y 400 en la práctica?

El 400 es para una petición que el servidor no puede interpretar en absoluto. El 422 es para una petición que se interpreta sin problema pero contiene un valor que falla una regla de validación o de negocio. Muchas API reales usan 400 para ambos casos, así que revisa siempre la convención documentada de la API concreta que estás llamando.

¿Puede un 422 significar que el servidor tiene un fallo?

Puede, si la propia regla de validación está mal, por ejemplo rechazando un formato de correo genuinamente válido. Pero un 422, por diseño, significa que el servidor está funcionando según lo previsto y objetando a los datos, así que investiga la regla de validación real antes de asumir que está rota.