Cada llamada /rest/ necesita la cabecera LinkedIn-Version en formato YYYYMM

¿Qué es la cabecera LinkedIn-Version?

Cada llamada a https://api.linkedin.com/rest/ lleva una cabecera LinkedIn-Version, y LinkedIn acepta un único formato de valor: seis dígitos, YYYYMM. La referencia de versionado lo resume en una frase: "Include a request header with the key Linkedin-Version and set the value to the version (format: YYYYMM) to correspond with the documentation version you are referencing."

La cabecera existe porque LinkedIn publica una versión nueva de la API cada mes y se niega a adivinar cuál querías. De esa misma página: "LinkedIn expects every versioned API call to specify a version; the latest version is not applied by default."

Una petición completa tiene este aspecto:

curl -X POST 'https://api.linkedin.com/rest/adCampaigns' \
-H 'X-Restli-Protocol-Version: 2.0.0' \
-H 'Authorization: Bearer {INSERT_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'Linkedin-Version: 202601' \
--data '{
    "account": "urn:li:sponsoredAccount:123212321",
    "audienceExpansionEnabled": false
}'

El versionado llegó con una ruta base nueva, no con un dominio nuevo. LinkedIn lo fecha con precisión: "LinkedIn's Marketing APIs first versioned API release was June 2022 under a new base path: https://api.linkedin.com/rest/." Todo lo que siga en https://api.linkedin.com/v2/ es anterior al esquema y se comporta de otra manera, algo que cubre la última sección.

¿Qué formato tiene el valor de la versión?

YYYYMM, año de cuatro dígitos seguido de mes de dos dígitos, sin separador y sin día. 202601 significa la versión publicada en enero de 2026. El ejemplo que da LinkedIn para migrar de una versión a la siguiente es un único cambio de cadena:

-H 'Linkedin-Version: 202501'  to  -H 'Linkedin-Version: 202601'

Valores recientes, copiados de la propia tabla de la página de versionado:

Agosto de 2026, 202608, es el valor que la página lista bajo "Latest Version" según su última actualización del 17 de agosto de 2026. El formato no cambia de un mes a otro, que es lo que hace segura la cabecera para montar una actualización rodada encima: un valor de configuración, seis caracteres, un despliegue.

Una incoherencia que anotar, porque va a confundir a quien haga coincidencias sobre el texto del error. El error de una versión muerta usa un marcador de ocho caracteres, "Requested version yyyymmdd is not active," mientras que el formato que LinkedIn exige es de seis. Ese marcador es el único sitio donde aparece yyyymmdd. Trátalo como una errata en la plantilla del mensaje, no como un segundo formato aceptado.

¿Se escribe LinkedIn-Version o Linkedin-Version?

La documentación de LinkedIn la escribe Linkedin-Version, con i minúscula en la segunda sílaba, en todas las páginas que la mencionan. La referencia de versionado, la Images API, la Posts API, la Videos API y la referencia de errores usan todas esa grafía, y el propio mensaje de error dice "by adding the Linkedin-Version header." El nombre de la empresa aparece como LinkedIn en cualquier otro sitio de esas mismas páginas.

Los nombres de campo de cabecera HTTP no distinguen mayúsculas, así que LinkedIn-Version, Linkedin-Version y linkedin-version llegan todos a la misma cabecera en el servidor. La grafía importa por un motivo más estrecho: si buscas LinkedIn-Version en la documentación de LinkedIn o en una colección de Postman, no encontrarás nada. Busca la grafía documentada.

¿Qué pasa cuando la cabecera falta o está obsoleta?

Dos fallos distintos con dos códigos de estado distintos, los dos documentados con cuerpos exactos.

El 426 es el interesante. HTTP 426 es Upgrade Required, y LinkedIn lo usa literalmente: la petición se entendió, la versión que nombraste ya no está, actualiza la cabecera. No es un 400, ni un 410, ni un 404, así que los manejadores de errores que solo ramifican por rangos 4xx lo mandarán a algún sitio inútil.

Los dos fallos ocurren antes de que corra ninguna lógica de negocio. Tu payload puede ser perfecto y tu token estar fresco, y aun así recibes un 400 si falta la cabecera. Eso es lo que convierte una cabecera de versión obsoleta en un modo de fallo tan silencioso en la publicación programada: nada cambia en tu código, pasa una fecha de retirada y todas las llamadas empiezan a devolver 426. Que la publicación se rompa para toda una cuenta de un día para otro, sin ningún cambio de código detrás, merece comprobarse contra la lista de causas de la pieza sobre las publicaciones programadas de LinkedIn que dejan de funcionar.

¿Cuánto dura una versión de la API de LinkedIn?

Un año como mínimo. La página de cadencia lo dice dos veces: "LinkedIn Marketing API Program publishes new versions monthly, and those versions are supported for a minimum of one (1) year," y "These API versions are supported and stable for a minimum of one year before sunset."

El aviso de obsolescencia que recorre la documentación de marketing es un ejemplo vivo de ese reloj: "The Marketing Version 202508 (Marketing August 2025) will be sunset on August 17, 2026." Doce meses y pico, anunciados por adelantado, en cada página.

El suelo de un año viene con una excepción declarada. LinkedIn "reserves the right to release a patch version to any API if required for any critical security, privacy issues, or bug fixes," y describe la probabilidad como mínima. Así que la garantía es que una versión sigue disponible un año, no que su comportamiento esté congelado un año.

Lo que eso significa en la práctica es una entrada de calendario y no una decisión de arquitectura. Fija la versión de forma explícita, revísala una vez al año y salta a la más reciente cuando lo hagas, ya que la propia guía de LinkedIn dice que migrar a la última te da "the option to wait up to one year before having to migrate again." La superficie de API que se apoya en esto, y lo que gobierna cada versión, está cubierto en la visión general de la Marketing API de LinkedIn.

¿Para qué sirve la cabecera X-Restli-Protocol-Version?

Para un trabajo completamente distinto, y se exige junto a la cabecera de versión, no en su lugar. La Posts API afirma las dos de un tirón: "All APIs require the request header Linkedin-Version: {Version in YYYYMM format}. All APIs require the request header X-Restli-Protocol-Version: 2.0.0."

LinkedIn-Version elige qué comportamiento de qué mes obtienes. X-Restli-Protocol-Version elige cómo se codifican tus URLs y parámetros de consulta, porque las APIs de LinkedIn están construidas sobre Rest.li. La página del protocolo es tajante sobre el valor por defecto: "To use version 2.0, you must pass X-Restli-Protocol-Version: 2.0.0 as the header in your API requests. If you don't pass a header, your call will default to version 1.0."

Caer a 1.0 no lanza ningún error. Cambia la sintaxis que el servidor espera, que es peor:

Así que una petición sin la cabecera de protocolo la parsean reglas para las que tu cliente no está escrito, y los errores resultantes señalan tus parámetros en lugar de la cabecera que falta. LinkedIn también señala que "plans to deprecate protocol version 1.0 in the near future" sin dar fecha. Envía 2.0.0 en cada llamada y la cuestión no vuelve a aparecer.

¿Qué endpoints de LinkedIn necesitan la cabecera de versión?

Los que están bajo /rest/. Los endpoints antiguos de /v2/ no la aceptan, y esa división explica casi toda la confusión en integraciones anteriores a 2022.

La guía de consumo Share on LinkedIn, que todavía documenta POST https://api.linkedin.com/v2/ugcPosts y POST https://api.linkedin.com/v2/assets?action=registerUpload, lista exactamente una cabecera obligatoria: "All requests require the following header: X-Restli-Protocol-Version: 2.0.0." En esa página no aparece ninguna cabecera de versión.

Toda llamada versionada de imagen y de publicación necesita las dos, y por eso la cabecera sale en cada petición de ejemplo del recorrido sobre cómo initializeUpload convierte un archivo en un URN de imagen, y por eso las filas de esquema que documentan límites como el techo de 4.086 caracteres de texto alternativo viven en páginas versionadas que cambian de mes a mes. Lee un límite de una versión que no estás enviando y estarás leyendo el contrato equivocado.

Preguntas frecuentes

¿Cuál es el formato correcto de la cabecera LinkedIn-Version?

Seis dígitos con forma YYYYMM, como Linkedin-Version: 202608. LinkedIn describe el valor como algo que corresponde "to the documentation version you are referencing," así que el valor de la cabecera y la página de documentación que estés leyendo deberían nombrar el mismo mes.

¿Qué error devuelve LinkedIn si falta la cabecera de versión?

400 con el código VERSION_MISSING y el mensaje "A version must be present. Please specify a version by adding the Linkedin-Version header." La comprobación corre antes de evaluar el cuerpo de la petición.

¿Qué es el HTTP 426 NONEXISTENT_VERSION en la API de LinkedIn?

La respuesta a una versión que ha sido retirada. El cuerpo documentado es {"status": 426, "code": "NONEXISTENT_VERSION", "message": "Requested version yyyymmdd is not active"}, y 426 es el estado Upgrade Required, que aquí significa actualizar el valor de la cabecera.

¿Con qué frecuencia publica LinkedIn una versión nueva de la API?

Cada mes. LinkedIn publica una versión nueva cada mes y mantiene cada una "for a minimum of one (1) year," con un registro de cambios por versión que lista qué recursos cambiaron.

¿Necesitas tanto LinkedIn-Version como X-Restli-Protocol-Version?

Sí, en los endpoints /rest/. La Posts API afirma que todas las APIs requieren Linkedin-Version en formato YYYYMM y que todas requieren X-Restli-Protocol-Version: 2.0.0, y una petición sin la segunda cae en silencio al protocolo 1.0 y a su sintaxis de consulta distinta.

¿Se escribe LinkedIn-Version o Linkedin-Version?

La documentación de LinkedIn usa Linkedin-Version en todas partes, incluido dentro del mensaje de error. Los nombres de campo HTTP no distinguen mayúsculas, así que cualquiera de las dos grafías llega al servidor, pero solo la documentada coincidirá con una búsqueda en las páginas del propio LinkedIn.

¿Se aplica la cabecera Linkedin-Version a los endpoints antiguos de v2?

No, esa exigencia se limita a la nueva ruta base. Linkedin-Version se requiere en las llamadas bajo https://api.linkedin.com/rest/, la ruta que LinkedIn introdujo en junio de 2022. Los endpoints antiguos de https://api.linkedin.com/v2/, como POST /v2/ugcPosts, no documentan esa cabecera en absoluto, solo X-Restli-Protocol-Version.

¿Puede cambiar el comportamiento de una versión de la API de LinkedIn después de publicarse?

LinkedIn puede hacerlo, dentro de ciertos límites. La empresa se reserva el derecho de publicar un parche sobre una versión por motivos críticos de seguridad, privacidad o errores, aunque describe esa posibilidad como mínima. El mínimo de un año de soporte garantiza que la versión siga disponible, no que su comportamiento quede congelado durante ese tiempo.

¿Qué cambió en la API de LinkedIn en junio de 2022?

Las Marketing APIs de LinkedIn recibieron ese mes su primera versión con numeración, bajo una nueva ruta base, https://api.linkedin.com/rest/. Todo lo que sigue funcionando en la ruta antigua https://api.linkedin.com/v2/ es anterior a ese cambio, sigue otras reglas y prescinde por completo de la cabecera Linkedin-Version.

¿Por qué una integración con LinkedIn que funcionaba puede fallar de la noche a la mañana?

La causa silenciosa más común es una cabecera de versión ya retirada. El código no cambia en nada, pero en cuanto termina el año mínimo de soporte de una versión, cada llamada que la nombra empieza a devolver 426 NONEXISTENT_VERSION en lugar de una respuesta correcta. La publicación programada es especialmente vulnerable, porque la cabecera suele configurarse una vez y no se revisa después.