Toda chamada /rest/ precisa do cabeçalho LinkedIn-Version no formato YYYYMM

O que é o cabeçalho LinkedIn-Version?

Toda chamada a https://api.linkedin.com/rest/ carrega um cabeçalho LinkedIn-Version, e o LinkedIn aceita um único formato de valor para ele: seis dígitos, YYYYMM. A referência de versionamento coloca isso em uma 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."

O cabeçalho existe porque o LinkedIn lança uma nova versão de API todo mês e se recusa a adivinhar qual você quis dizer. Da mesma página: "LinkedIn expects every versioned API call to specify a version; the latest version is not applied by default."

Uma requisição completa fica assim:

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
}'

O versionamento chegou com um caminho base novo, e não com um domínio novo. O LinkedIn data isso com precisão: "LinkedIn's Marketing APIs first versioned API release was June 2022 under a new base path: https://api.linkedin.com/rest/." Qualquer coisa ainda em https://api.linkedin.com/v2/ é anterior ao esquema e se comporta de outro jeito, o que a última seção cobre.

Que formato o valor da versão usa?

YYYYMM, ano com quatro dígitos seguido de mês com dois, sem separador e sem dia. 202601 significa a versão publicada em janeiro de 2026. O exemplo que o LinkedIn dá para migrar de uma versão para a seguinte é uma troca de string única:

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

Valores recentes, copiados da própria tabela da página de versionamento:

August 2026, 202608, é o valor que a página lista sob "Latest Version" na sua última atualização, de 17 de agosto de 2026. Nada no formato muda de mês para mês, o que torna o cabeçalho seguro para construir uma atualização rotativa em volta: um valor de configuração, seis caracteres, um deploy.

Uma inconsistência a registrar, porque vai confundir quem casa texto de erro. O erro de uma versão morta usa um marcador de oito caracteres, "Requested version yyyymmdd is not active," enquanto o formato que o LinkedIn exige tem seis caracteres. O marcador é o único lugar em que yyyymmdd aparece. Trate como erro de digitação no modelo da mensagem, e não como um segundo formato aceito.

Escreve-se LinkedIn-Version ou Linkedin-Version?

A documentação do LinkedIn escreve Linkedin-Version, com i minúsculo na segunda sílaba, em toda página que o menciona. A referência de versionamento, a Images API, a Posts API, a Videos API e a referência de erros todas usam essa grafia, e a própria mensagem de erro diz "by adding the Linkedin-Version header." O nome da empresa aparece como LinkedIn em todo o resto dessas mesmas páginas.

Nomes de campo de cabeçalho HTTP não diferenciam maiúsculas de minúsculas, então LinkedIn-Version, Linkedin-Version e linkedin-version chegam todos ao mesmo cabeçalho no servidor. A grafia importa por uma razão mais estreita: se você fizer grep por LinkedIn-Version na documentação do LinkedIn ou numa coleção do Postman, não vai achar nada. Busque pela grafia documentada.

O que acontece quando o cabeçalho está ausente ou velho?

Duas falhas distintas com dois códigos de status distintos, ambas documentadas com corpos exatos.

O 426 é o interessante. HTTP 426 é Upgrade Required, e o LinkedIn o usa literalmente: a requisição foi entendida, a versão que você nomeou acabou, atualize o cabeçalho. Não é um 400, nem um 410, nem um 404, então tratadores de erro que só ramificam por faixas 4xx vão encaminhá-lo para algum lugar inútil.

As duas falhas acontecem antes de qualquer lógica de negócio rodar. Seu payload pode estar perfeito e seu token fresco, e você ainda leva um 400 se o cabeçalho estiver ausente. É isso que faz de um cabeçalho de versão velho um modo de falha tão silencioso em publicação agendada: nada muda no seu código, uma data de descontinuação passa, e toda chamada começa a devolver 426. Publicação que quebra para uma conta inteira da noite para o dia, sem mudança de código por trás, vale checar contra a lista de causas no texto sobre posts agendados do LinkedIn que param de funcionar.

Quanto tempo dura uma versão da API do LinkedIn?

No mínimo um ano. A página de cadência afirma isso duas vezes: "LinkedIn Marketing API Program publishes new versions monthly, and those versions are supported for a minimum of one (1) year," e "These API versions are supported and stable for a minimum of one year before sunset."

O aviso de descontinuação que corre pela documentação de marketing é um exemplo vivo desse relógio: "The Marketing Version 202508 (Marketing August 2025) will be sunset on August 17, 2026." Doze meses e pouco, anunciados com antecedência, em toda página.

O piso de um ano vem com uma exceção declarada. O LinkedIn "reserves the right to release a patch version to any API if required for any critical security, privacy issues, or bug fixes," descrevendo a probabilidade como mínima. Ou seja, a garantia é de que uma versão fica disponível por um ano, não de que o comportamento dela fica congelado por um ano.

O que isso significa na prática é um lembrete no calendário, e não uma decisão de arquitetura. Fixe a versão explicitamente, revise uma vez por ano e pule para a versão mais nova quando revisar, já que a orientação do próprio LinkedIn é que migrar para a mais recente te compra "the option to wait up to one year before having to migrate again." A superfície de API que fica em cima disso, e o que cada versão de fato governa, está coberta na visão geral sobre a Marketing API do LinkedIn.

Para que serve o cabeçalho X-Restli-Protocol-Version?

Para um trabalho totalmente diferente, e ele é exigido junto do cabeçalho de versão, não no lugar dele. A Posts API declara os dois de uma vez: "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."

O LinkedIn-Version escolhe o comportamento de qual mês da API você recebe. O X-Restli-Protocol-Version escolhe como suas URLs e parâmetros de consulta são codificados, porque as APIs do LinkedIn são construídas sobre Rest.li. A página do protocolo é direta sobre o padrão: "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."

Cair para 1.0 não lança erro. Muda a sintaxe que o servidor espera, o que é pior:

Ou seja, uma requisição sem o cabeçalho de protocolo é interpretada por regras que o seu cliente não está escrevendo, e os erros resultantes apontam para os seus parâmetros em vez de para o cabeçalho ausente. O LinkedIn também nota que "plans to deprecate protocol version 1.0 in the near future" sem dar data. Mande 2.0.0 em toda chamada e a questão nunca aparece.

Quais endpoints do LinkedIn precisam do cabeçalho de versão?

Os que ficam sob /rest/. Os endpoints mais antigos /v2/ não o recebem, e essa divisão explica a maior parte da confusão em integrações anteriores a 2022.

O guia consumidor Share on LinkedIn, que ainda documenta POST https://api.linkedin.com/v2/ugcPosts e POST https://api.linkedin.com/v2/assets?action=registerUpload, lista exatamente um cabeçalho obrigatório: "All requests require the following header: X-Restli-Protocol-Version: 2.0.0." Nenhum cabeçalho de versão aparece naquela página.

Toda chamada versionada de imagem e de post precisa dos dois, e é por isso que o cabeçalho aparece em cada requisição de exemplo do passo a passo sobre como o initializeUpload transforma um arquivo em URN de imagem, e por isso que as linhas de schema que documentam limites como o teto de 4.086 caracteres de alt text moram em páginas versionadas que mudam de mês para mês. Leia um limite de uma versão que você não está enviando e estará lendo o contrato errado.

Perguntas frequentes

Qual é o formato correto do cabeçalho LinkedIn-Version?

Seis dígitos na forma YYYYMM, como Linkedin-Version: 202608. O LinkedIn descreve o valor como correspondente "to the documentation version you are referencing," então o valor do cabeçalho e a página de documentação que você está lendo devem nomear o mesmo mês.

Que erro o LinkedIn devolve se o cabeçalho de versão estiver ausente?

400 com o código VERSION_MISSING e a mensagem "A version must be present. Please specify a version by adding the Linkedin-Version header." A checagem roda antes de o corpo da requisição ser avaliado.

O que é o HTTP 426 NONEXISTENT_VERSION na API do LinkedIn?

A resposta a uma versão que foi descontinuada. O corpo documentado é {"status": 426, "code": "NONEXISTENT_VERSION", "message": "Requested version yyyymmdd is not active"}, e 426 é o status Upgrade Required, que aqui significa atualizar o valor do cabeçalho.

Com que frequência o LinkedIn lança uma nova versão de API?

Mensalmente. O LinkedIn publica uma versão nova a cada mês e suporta cada uma "for a minimum of one (1) year," com um changelog por versão listando quais recursos mudaram.

É preciso usar LinkedIn-Version e X-Restli-Protocol-Version juntos?

Sim, em endpoints /rest/. A Posts API afirma que todas as APIs exigem Linkedin-Version no formato YYYYMM e que todas exigem X-Restli-Protocol-Version: 2.0.0, e uma requisição sem o segundo cai em silêncio para o protocolo 1.0 e sua sintaxe de consulta diferente.

O cabeçalho se escreve LinkedIn-Version ou Linkedin-Version?

A documentação do LinkedIn usa Linkedin-Version em todo lugar, inclusive dentro da mensagem de erro. Nomes de campo HTTP não diferenciam maiúsculas de minúsculas, então qualquer grafia chega ao servidor, mas só a documentada vai casar com uma busca nas páginas do próprio LinkedIn.

O cabeçalho Linkedin-Version também vale para os endpoints antigos da v2?

Não, essa exigência vale só para o novo caminho base. O Linkedin-Version é exigido nas chamadas sob https://api.linkedin.com/rest/, o caminho que o LinkedIn introduziu em junho de 2022. Os endpoints antigos em https://api.linkedin.com/v2/, como POST /v2/ugcPosts, não documentam esse cabeçalho, só o X-Restli-Protocol-Version.

O comportamento de uma versão da API do LinkedIn pode mudar depois de lançada?

O LinkedIn pode fazer isso, dentro de certos limites. A empresa se reserva o direito de lançar um patch numa versão por questões críticas de segurança, privacidade ou correção de bugs, embora chame essa chance de mínima. O mínimo de um ano de suporte garante que a versão continue acessível, não que seu comportamento fique congelado durante esse ano.

O que mudou na API do LinkedIn em junho de 2022?

As Marketing APIs do LinkedIn receberam naquele mês seu primeiro lançamento versionado, sob um novo caminho base, https://api.linkedin.com/rest/. Tudo o que ainda roda no caminho antigo https://api.linkedin.com/v2/ é anterior a essa mudança, segue regras diferentes e dispensa por completo o cabeçalho Linkedin-Version.

Por que uma integração com o LinkedIn que funcionava pode parar de funcionar do dia para a noite?

A causa silenciosa mais comum é um cabeçalho de versão já desativado. Nada muda no código, mas assim que o ano mínimo de suporte de uma versão termina, toda chamada que a nomeia passa a retornar 426 NONEXISTENT_VERSION em vez de uma resposta correta. A publicação agendada fica especialmente exposta, porque o cabeçalho costuma ser configurado uma vez e nunca mais revisado.