HTTP 422 Contenido no procesable: qué significa y cómo solucionarlo

Qué significa este error y cómo reconocerlo

• Un navegador, cliente de API, servicio de monitorización o comprobador de sitios web recibe una respuesta HTTP 422 Unprocessable Content.
• El servidor devuelve una respuesta HTTP, por lo que la solicitud llegó a un endpoint que habla HTTP; la resolución DNS y la negociación TLS aún pueden estar funcionando con normalidad.
• El fallo afecta a una URL, método HTTP, envío de formulario, payload de API o acción de usuario concretos, en lugar de afectar a todo el sitio.
• La respuesta puede incluir un cuerpo de error que indique un campo, valor, estado o regla de validación no válidos.
• Las cabeceras de respuesta pueden identificar información de caché, autenticación, proxy, limitación de tasa, seguimiento de solicitudes o servidor que ayude a localizar el origen.

Causas principales, ordenadas por probabilidad

Las causas más probables son:

1. Fallo de validación de la aplicación. Puede faltar un campo obligatorio, un valor puede estar fuera del intervalo permitido o una combinación de campos válidos por separado puede no ser aceptable para la operación.
2. La solicitud no coincide con el método o la representación esperados por la ruta. La URL, el método HTTP, el tipo de contenido, la estructura del cuerpo o los datos codificados pueden no coincidir con lo que el endpoint está diseñado para procesar.
3. Estado de recurso no válido o regla de negocio. La solicitud puede ser sintácticamente válida, pero imposible en el estado actual, como una operación que entra en conflicto con las reglas de la aplicación.
4. Una regla del servidor, proxy inverso, CDN o WAF. Un intermediario puede validar o transformar la solicitud y devolver 422 antes de que llegue a la aplicación.
5. Cambios recientes de routing o despliegue. Un esquema, serializador, regla de middleware o integración upstream modificados pueden hacer que fallen solicitudes que antes se aceptaban.
6. Contexto de autenticación o autorización. Estos factores pueden contribuir cuando la aplicación valida una operación autenticada o el estado de una solicitud, pero un 422 aislado no debe diagnosticarse automáticamente como un error de inicio de sesión o permisos. Comprueba la respuesta y los registros para distinguirlo de 401 o 403.

Cómo solucionarlo

Si estás visitando el sitio web

1. Reintenta una vez y verifica la solicitud. Comprueba la URL, los valores seleccionados del formulario, los datos cargados y cualquier campo obligatorio. No envíes repetidamente la misma acción si puede crear un registro o activar un límite.
2. Usa el flujo normal de la cuenta. Si la acción requiere una cuenta, inicia sesión mediante la interfaz habitual del sitio y vuelve a intentarlo. No pegues contraseñas, cookies ni tokens en las solicitudes de soporte.
3. Comprueba si el fallo se limita a una acción. Si las páginas normales funcionan, pero un formulario, carga o acción de checkout devuelve 422, anota esa acción, la hora aproximada y el mensaje de error visible.
4. Prueba únicamente un cliente alternativo adecuado. Si el propietario del sitio lo permite, una ventana privada u otro navegador compatible puede ayudar a distinguir un problema local del formulario o de la sesión de una respuesta del servidor. No eludas los controles de seguridad.
5. Contacta con el propietario del sitio si persiste. Proporciona la URL afectada, el tipo de solicitud si lo conoces, la hora del fallo y los detalles del error una vez desinfectados. Evita enviar credenciales, cookies de sesión, datos de pago o secretos de API.

Si eres desarrollador o propietario del sitio

1. Captura la solicitud y la respuesta exactas. Registra el método HTTP, la URL, los parámetros de consulta, el tipo de contenido, los campos relevantes del cuerpo, el estado, el cuerpo de respuesta y las cabeceras de respuesta. Redacta los secretos y datos personales.
2. Confirma que 422 es la respuesta final. Comprueba si hay redirecciones, respuestas almacenadas en caché o un intermediario que pueda estar ocultando la respuesta de la aplicación. Compara el resultado con una solicitud válida conocida para la misma ruta.
3. Valida la solicitud frente al contrato del endpoint. Comprueba los campos obligatorios, los tipos de datos, los valores permitidos, la codificación, el tipo de contenido, los identificadores de recursos y cualquier requisito de orden o estado. Distingue la validación semántica de la sintaxis mal formada, que puede producir un estado diferente.
4. Identifica la capa que lo genera. Usa cabeceras de respuesta distintivas, identificadores de solicitud, registros de acceso, registros de la aplicación, registros del proxy inverso, registros de la CDN o eventos del WAF para determinar si el 422 procede de la aplicación o de un intermediario.
5. Compara una solicitud fallida con una correcta. Cambia un detalle relevante cada vez, como el método, el valor de un campo, el tipo de contenido, el estado autenticado o el recurso de destino. Mantén la reproducción al mínimo para que la regla de validación real sea visible.
6. Revisa los cambios recientes. Comprueba los despliegues, las definiciones de rutas, los esquemas, los serializadores, el middleware, la política de autenticación, las reglas del proxy, el comportamiento de la caché y las integraciones upstream alrededor del primer fallo.
7. Aplica la corrección autorizada más específica. Corrige el contrato de la solicitud, la regla de validación, la ruta o la configuración del intermediario que explique las evidencias. Evita cambios amplios de permisos, seguridad, caché o proxy sin un plan de reversión probado.
8. Vuelve a probar de forma segura y verifica el comportamiento relacionado. Repite la misma solicitud en un entorno controlado cuando sea posible y confirma después que los métodos y rutas relacionados siguen devolviendo los estados previstos. Si el cambio afecta a producción, sigue los procedimientos de gestión de cambios y aprobación del servicio.

Prevención y cómo verificar la solución

• Documenta los métodos aceptados, tipos de contenido, campos obligatorios, valores permitidos y respuestas de validación esperadas de cada endpoint.
• Valida los datos de las solicitudes de forma coherente en el límite adecuado de la aplicación y devuelve un cuerpo de error práctico que no contenga información sensible.
• Añade pruebas para campos obligatorios, valores no válidos, conflictos de estado de recursos y solicitudes representativas de clientes.
• Supervisa las tasas de 422 por ruta, método, cliente y despliegue para distinguir una regresión del tráfico de validación normal.
• Mantén la configuración de routing, esquemas, proxy, autenticación, CDN y WAF bajo un control de versiones que permita revisiones.
• Conserva los identificadores de solicitud y los registros relevantes durante el tiempo suficiente para correlacionar una respuesta HTTP con el componente que la genera, redactando secretos y datos sensibles.
• Prueba los formularios y métodos de API importantes después de lanzamientos, cambios de esquema y actualizaciones de la configuración de intermediarios.

Preguntas frecuentes