Content-Length

Uso

La cabecera Content-Length comunica el tamaño exacto en bytes del cuerpo del mensaje HTTP. Los clientes se basan en este valor para saber cuándo se ha recibido por completo una respuesta, lo que deja la conexión disponible para su reutilización en las conexiones persistentes de HTTP/1.1.

Cuando un servidor envía una respuesta cuyo tamaño de cuerpo se conoce, la cabecera Content-Length permite al cliente reservar la cantidad de memoria adecuada y mostrar indicadores de progreso precisos durante las descargas. Una discrepancia entre la longitud declarada y el tamaño real del cuerpo indica una transferencia truncada o dañada.

Esta cabecera es mutuamente excluyente con Transfer-Encoding en modo chunked. Cuando un servidor transmite en flujo una respuesta de tamaño desconocido, la codificación chunked sustituye a una longitud de contenido fija. En HTTP/2 y HTTP/3, el sistema de tramas gestiona los límites de los mensajes a nivel de protocolo, pero Content-Length sigue siendo válida para validar el tamaño del cuerpo.

El valor es un único número entero no negativo que representa la cantidad de octetos (bytes) del cuerpo del mensaje.

Ejemplo

Un servidor devuelve una respuesta JSON de 3.495 bytes. El cliente lee exactamente 3.495 bytes antes de considerar completo el mensaje.

Content-Length: 3495

Una solicitud POST envía un cuerpo de formulario. La cabecera Content-Length indica al servidor cuántos bytes debe esperar en el cuerpo de la solicitud.

POST /submit HTTP/1.1
Host: example.re
Content-Type: application/x-www-form-urlencoded
Content-Length: 27

field=value&other=something

Una respuesta que usa la codificación de transferencia chunked omite por completo la cabecera Content-Length. La cabecera Transfer-Encoding tiene prioridad.

Transfer-Encoding: chunked

Diagnóstico

Los fallos de transferencia y los errores de conexión suelen deberse a un valor de Content-Length incorrecto o contradictorio.

Transferencia interrumpida o descarga parcial. El cliente recibe menos bytes de los que declara Content-Length e informa de una respuesta truncada. Causas habituales: el origen cierra la conexión antes de tiempo, un tiempo de espera del proxy corta la transferencia o el servidor calcula mal el tamaño del cuerpo. Ejecute curl -v https://example.re/file y compare el valor de la cabecera Content-Length con los bytes realmente recibidos (que aparecen en el resumen de la transferencia). Una discrepancia confirma el problema.

Codificación chunked y Content-Length presentes a la vez. Enviar Transfer-Encoding: chunked y Content-Length en la misma respuesta infringe la especificación HTTP. Los clientes deben ignorar Content-Length cuando Transfer-Encoding está presente, pero no todas las implementaciones cumplen esta regla. Elimine Content-Length cuando use la codificación chunked. En nginx, la codificación chunked se aplica automáticamente cuando el tamaño del cuerpo es desconocido, y en ese caso nginx omite Content-Length. El código de aplicación personalizado o el middleware que establece ambas cabeceras debe corregirse.

Content-Length incorrecta después de que el middleware modifique el cuerpo. El middleware que inyecta contenido (scripts de analítica, tokens de seguridad, barras de depuración) cambia el tamaño del cuerpo sin actualizar Content-Length. El navegador o bien trunca el contenido visible, o bien espera bytes que nunca llegan. Traslade el cálculo de Content-Length a la etapa final, una vez completadas todas las modificaciones del cuerpo. En Express.js, el middleware compression se encarga de ello automáticamente. En configuraciones propias, elimine Content-Length y apóyese en la codificación chunked.

La respuesta a HEAD lleva una Content-Length incorrecta. Una respuesta HEAD debe incluir la misma Content-Length que llevaría la respuesta GET correspondiente, pero sin cuerpo. Algunos frameworks generan respuestas HEAD con una Content-Length de 0 u omiten la cabecera por completo. Compruébelo comparando curl -I https://example.re/resource (HEAD) con curl -s -o /dev/null -w ’%{size_download}’ https://example.re/resource (tamaño del cuerpo de GET). Los valores discrepantes rompen los gestores de descargas y los proxies de caché que se basan en HEAD para determinar el tamaño del recurso.

Diagnosticar problemas de Content-Length con curl. Ejecute curl -v https://example.re/resource para ver la cabecera Content-Length y el recuento de bytes transferidos en la salida detallada. La línea Content-Length: N muestra el tamaño declarado. Al final, bytes received muestra la transferencia real. Añada -o /dev/null para descartar el cuerpo y centrarse en las cabeceras. En las respuestas comprimidas, recuerde que Content-Length refleja el tamaño comprimido, no el tamaño original.