HTTP 415 Unsupported Media Type: qué significa y cómo solucionarlo

Qué significa este error y cómo reconocerlo

• Un cliente de API, formulario del navegador, herramienta de carga, comprobación de monitorización o aplicación informa de 415 Unsupported Media Type.
• La respuesta puede afectar a un endpoint, método HTTP o formato de solicitud concreto, mientras que otras páginas y rutas siguen funcionando.
• Una solicitud puede fallar después de cambiar el formato del cuerpo, Content-Type, la codificación del contenido, el tipo de archivo subido o la biblioteca cliente.
• Las cabeceras de respuesta pueden revelar qué servidor, proxy o CDN generó la respuesta, junto con información sobre caché, autenticación, redirecciones o límites de frecuencia.
• La resolución DNS y la negociación TLS pueden tener éxito porque se recibió una respuesta HTTP; esas comprobaciones no demuestran que el contenido de la solicitud fuera aceptable.

Causas principales, ordenadas por probabilidad

1. Tipo de medio de la solicitud no compatible: El endpoint no acepta el valor enviado en Content-Type, por ejemplo, cuando se envían datos de formulario a una ruta que solo acepta JSON.
2. Cabecera de solicitud incorrecta o ausente: El cliente omite Content-Type, envía un error tipográfico o describe el cuerpo de forma distinta a su formato real.
3. Codificación del contenido no compatible: La solicitud usa una codificación de compresión o transferencia que el componente receptor no puede procesar.
4. Endpoint o método incorrecto: Se envía una solicitud a una ruta que espera una representación, formato de carga o método HTTP diferente.
5. Validación del proxy, CDN, WAF o servidor web: Un intermediario rechaza la solicitud antes de que llegue a la aplicación o aplica reglas distintas de los requisitos documentados de la aplicación.
6. Cambio reciente en la aplicación o la configuración: Un despliegue, cambio de enrutamiento, actualización del parser, integración de autenticación o regla del proxy modifica los formatos de solicitud aceptados.

El código de estado por sí solo no identifica el componente responsable. Confirma los detalles de la solicitud y los logs correspondientes antes de atribuir la causa a la autenticación, los permisos, los límites o la configuración upstream.

Cómo solucionarlo

Para visitantes y usuarios no técnicos

1. Repite la acción exacta una vez. Confirma la URL y, si corresponde, la acción de carga o envío de formulario que seleccionaste. Evita enviar repetidamente la misma solicitud.
2. Usa el flujo normal de inicio de sesión. Si el endpoint requiere una cuenta, inicia sesión mediante la interfaz habitual del sitio en lugar de cambiar manualmente las cabeceras o cookies de la solicitud.
3. Comprueba el archivo o contenido enviado. Si el error ocurre durante una carga o el envío de un formulario, utiliza el formato solicitado por el sitio y evita cambiar el nombre de un archivo sin convertirlo.
4. Prueba la interfaz compatible del sitio. Si falla una herramienta de API, extensión del navegador o integración personalizada, compárala con el formulario web o la aplicación habitual del sitio.
5. Contacta con el propietario del sitio si el problema persiste. Incluye la URL o función afectada, la hora aproximada, el resultado HTTP 415 y la acción que falló. No envíes contraseñas, cookies, tokens de autorización ni el contenido privado de archivos.

Para desarrolladores y clientes de API

1. Captura la estructura completa de la solicitud. Registra el método, la ruta de la URL, los parámetros de consulta, Content-Type, la codificación del contenido, el valor relevante de Accept y una descripción saneada del cuerpo. No registres secretos ni datos personales innecesariamente.
2. Compara la solicitud con el contrato del endpoint. Verifica que la ruta y el método acepten la representación que se está enviando. Por ejemplo, confirma si el endpoint espera JSON, datos codificados como formulario, datos de formulario multipart, XML o un formato de carga específico.
3. Haz que la declaración coincida con el cuerpo. No etiquetes datos de formulario como JSON ni envíes un cuerpo comprimido sin la codificación compatible correspondiente. Deja que la biblioteca cliente construya los límites multipart cuando ofrezca esa función.
4. Usa una reproducción mínima. Elimina los campos opcionales y el middleware no relacionado cuando sea posible; después, repite la misma solicitud con un cuerpo compatible conocido. Conserva la solicitud original para compararla.
5. Inspecciona la respuesta. Comprueba el estado, Content-Type, los indicadores de caché, los identificadores del servidor o proxy, las redirecciones y cualquier cuerpo de error. Una respuesta generada por un gateway puede no reflejar la validación propia de la aplicación.
6. Comprueba los logs de la capa responsable. Compara la marca de tiempo, la ruta y el identificador de correlación o de solicitud con los logs de la aplicación, el servidor web, el proxy inverso, la CDN o el WAF.
7. Aplica la corrección más específica. Corrige la cabecera del cliente, el serializador, el formato de carga, el contrato de la ruta o la regla del intermediario con el alcance más limitado posible. No desactives ampliamente la validación, la autenticación ni el filtrado de seguridad como primera respuesta.
8. Vuelve a probar y comprueba el comportamiento relacionado. Repite la solicitud original; después, prueba el mismo endpoint con sus formatos compatibles y verifica que las rutas relacionadas sigan devolviendo los códigos de estado previstos.

Para propietarios y operadores de sitios

1. Reproduce el fallo desde el mismo tipo de cliente y método de solicitud, capturando las cabeceras saneadas y los tiempos.
2. Determina si el 415 fue generado por la aplicación, el servidor web, el proxy inverso, la CDN o el WAF comparando las cabeceras de respuesta y los logs de cada capa.
3. Revisa los despliegues recientes y los cambios en el enrutamiento, el análisis de solicitudes, la gestión de cargas, el reenvío del proxy, la codificación del contenido y las reglas de seguridad.
4. Confirma que las cachés o los intermediarios no estén sirviendo una respuesta almacenada inadecuada para la solicitud.
5. Corrige la ruta o el contrato específico del cliente, documenta los formatos aceptados y conserva suficientes logs para confirmar la solución.
6. Si la solicitud no es compatible de forma intencionada, asegúrate de que el comportamiento del endpoint y la documentación para clientes indiquen claramente el formato aceptado.

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

• Documenta los métodos HTTP, tipos de medios, codificaciones y formatos de carga aceptados para cada endpoint importante.
• Usa pruebas automatizadas para solicitudes representativas de JSON, formularios, multipart y otros tipos compatibles después de cambios en la aplicación o el proxy.
• Mantén la configuración de enrutamiento, análisis de solicitudes, proxy, CDN y WAF bajo control de versiones, con cambios que puedan revisarse.
• Supervisa los códigos de estado por ruta y método en lugar de tratar todas las respuestas 4xx como una sola categoría.
• Mantén disponibles los identificadores de correlación y los logs de la aplicación y los intermediarios, debidamente saneados, durante el periodo de conservación correspondiente.
• Haz que las integraciones de clientes fallen claramente cuando cambien los tipos de medios aceptados por el servidor y pruébalas contra el contrato documentado.

Preguntas frecuentes