Chaque appel /rest/ exige l'en-tête LinkedIn-Version au format YYYYMM

Qu'est-ce que l'en-tête LinkedIn-Version ?

Chaque appel vers https://api.linkedin.com/rest/ porte un en-tête LinkedIn-Version, et LinkedIn n'accepte qu'un seul format de valeur : six chiffres, YYYYMM. La référence sur le versionnage le dit en une phrase : « 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. »

L'en-tête existe parce que LinkedIn livre une nouvelle version d'API chaque mois et refuse de deviner laquelle vous vouliez. Sur la même page : « LinkedIn expects every versioned API call to specify a version; the latest version is not applied by default. »

Une requête complète ressemble à ceci :

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

Le versionnage est arrivé avec un nouveau chemin de base, pas un nouveau domaine. LinkedIn le date précisément : « LinkedIn's Marketing APIs first versioned API release was June 2022 under a new base path: https://api.linkedin.com/rest/. » Tout ce qui est encore sur https://api.linkedin.com/v2/ est antérieur au dispositif et se comporte différemment, ce que couvre la dernière section.

Quel format la valeur de version prend-elle ?

YYYYMM, année sur quatre chiffres suivie du mois sur deux chiffres, sans séparateur et sans jour. 202601 désigne la version publiée en janvier 2026. L'exemple que donne LinkedIn pour migrer d'une version à la suivante est un simple échange de chaîne :

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

Valeurs récentes, copiées du tableau de la page de versionnage :

Août 2026, 202608, est la valeur que la page liste sous « Latest Version » à sa dernière mise à jour du 17 août 2026. Rien du format ne change d'un mois à l'autre, ce qui rend l'en-tête sûr pour bâtir une montée de version continue : une valeur de configuration, six caractères, un déploiement.

Une incohérence à signaler, parce qu'elle troublera quiconque fait correspondre du texte d'erreur. L'erreur pour une version morte utilise un substitut de huit caractères, « Requested version yyyymmdd is not active », alors que le format exigé par LinkedIn fait six caractères. Ce substitut est le seul endroit où yyyymmdd apparaît. Traitez-le comme une coquille dans le modèle de message, pas comme un second format accepté.

L'orthographe est-elle LinkedIn-Version ou Linkedin-Version ?

La documentation de LinkedIn écrit Linkedin-Version, avec un i minuscule à la seconde syllabe, sur chaque page qui le mentionne. La référence de versionnage, l'Images API, la Posts API, la Videos API et la référence des erreurs utilisent toutes cette orthographe, et le message d'erreur lui-même dit « by adding the Linkedin-Version header. » Le nom de l'entreprise s'écrit LinkedIn partout ailleurs sur ces mêmes pages.

Les noms de champs d'en-tête HTTP ne sont pas sensibles à la casse, donc LinkedIn-Version, Linkedin-Version et linkedin-version atteignent tous le même en-tête sur le serveur. L'orthographe compte pour une raison plus étroite : si vous cherchez LinkedIn-Version dans la documentation de LinkedIn ou dans une collection Postman, vous ne trouverez rien. Cherchez l'orthographe documentée à la place.

Que se passe-t-il quand l'en-tête est absent ou périmé ?

Deux échecs distincts avec deux codes de statut distincts, tous deux documentés avec des corps exacts.

Le 426 est le plus intéressant. HTTP 426 signifie Upgrade Required, et LinkedIn l'emploie littéralement : la requête a été comprise, la version que vous avez nommée a disparu, mettez l'en-tête à jour. Ce n'est ni un 400, ni un 410, ni un 404, donc les gestionnaires d'erreurs qui ne branchent que sur des plages 4xx l'enverront quelque part d'inutile.

Les deux échecs se produisent avant que la moindre logique métier ne s'exécute. Votre charge utile peut être parfaite et votre jeton tout frais, vous obtenez quand même un 400 si l'en-tête est absent. C'est ce qui fait d'un en-tête de version périmé un mode de défaillance aussi silencieux dans la publication planifiée : rien ne change dans votre code, une date de retrait passe, et tous les appels se mettent à renvoyer 426. Une publication qui casse pour un compte entier du jour au lendemain, sans aucun changement de code derrière, vaut la peine d'être confrontée à la liste des causes de l'article sur les posts LinkedIn planifiés qui cessent de fonctionner.

Combien de temps dure une version de l'API LinkedIn ?

Un an au minimum. La page sur la cadence le dit deux fois : « LinkedIn Marketing API Program publishes new versions monthly, and those versions are supported for a minimum of one (1) year », et « These API versions are supported and stable for a minimum of one year before sunset. »

Le bandeau de dépréciation qui traverse la documentation marketing est un exemple vivant de cette horloge : « The Marketing Version 202508 (Marketing August 2025) will be sunset on August 17, 2026. » Douze mois et quelques, annoncés à l'avance, sur chaque page.

Le plancher d'un an s'accompagne d'une exception déclarée. LinkedIn « reserves the right to release a patch version to any API if required for any critical security, privacy issues, or bug fixes », en décrivant la probabilité comme minime. La garantie est donc qu'une version reste disponible pendant un an, pas que son comportement soit figé pendant un an.

Ce que cela veut dire en pratique est une entrée d'agenda plutôt qu'une décision d'architecture. Épinglez la version explicitement, revoyez-la une fois par an, et sautez à la plus récente quand vous le faites, puisque le conseil de LinkedIn est que migrer vers la dernière vous achète « the option to wait up to one year before having to migrate again. » La surface d'API qui repose là-dessus, et ce que chaque version gouverne réellement, sont traitées dans la présentation de la LinkedIn Marketing API.

À quoi sert l'en-tête X-Restli-Protocol-Version ?

À un tout autre travail, et il est exigé à côté de l'en-tête de version plutôt qu'à sa place. La Posts API énonce les deux d'un même souffle : « 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 choisit le comportement d'API de quel mois vous obtenez. X-Restli-Protocol-Version choisit comment vos URL et vos paramètres de requête sont encodés, parce que les API de LinkedIn sont bâties sur Rest.li. La page du protocole est franche sur la valeur par défaut : « 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. »

Retomber en 1.0 ne lève aucune erreur. Cela change la syntaxe que le serveur attend, ce qui est pire :

Donc une requête à laquelle manque l'en-tête de protocole est analysée par des règles que votre client n'écrit pas, et les erreurs qui en sortent pointent vers vos paramètres plutôt que vers l'en-tête manquant. LinkedIn note aussi qu'il « plans to deprecate protocol version 1.0 in the near future » sans donner de date. Envoyez 2.0.0 à chaque appel et la question ne se pose jamais.

Quels endpoints LinkedIn ont besoin de l'en-tête de version ?

Ceux sous /rest/. Les anciens endpoints /v2/ ne le prennent pas, et cette séparation explique l'essentiel de la confusion dans les intégrations antérieures à 2022.

Le guide grand public Share on LinkedIn, qui documente encore POST https://api.linkedin.com/v2/ugcPosts et POST https://api.linkedin.com/v2/assets?action=registerUpload, liste exactement un en-tête obligatoire : « All requests require the following header: X-Restli-Protocol-Version: 2.0.0. » Aucun en-tête de version n'apparaît sur cette page.

Chaque appel d'image et de post versionné a besoin des deux, ce qui explique que l'en-tête figure dans chaque exemple de requête du pas-à-pas sur comment initializeUpload transforme un fichier en URN d'image, et que les lignes de schéma qui documentent des limites comme le plafond de 4 086 caractères de texte alternatif vivent sur des pages versionnées qui changent d'un mois à l'autre. Lisez une limite sur une version que vous n'envoyez pas, et vous lisez le mauvais contrat.

Questions fréquentes

Quel est le format correct de l'en-tête LinkedIn-Version ?

Six chiffres sous la forme YYYYMM, par exemple Linkedin-Version: 202608. LinkedIn décrit la valeur comme correspondant « to the documentation version you are referencing », donc la valeur de l'en-tête et la page de documentation que vous lisez devraient nommer le même mois.

Quelle erreur LinkedIn renvoie-t-il si l'en-tête de version est absent ?

400 avec le code VERSION_MISSING et le message « A version must be present. Please specify a version by adding the Linkedin-Version header. » La vérification s'exécute avant que le corps de la requête ne soit évalué.

Qu'est-ce que le HTTP 426 NONEXISTENT_VERSION sur l'API LinkedIn ?

La réponse à une version retirée du service. Le corps documenté est {"status": 426, "code": "NONEXISTENT_VERSION", "message": "Requested version yyyymmdd is not active"}, et 426 est le statut Upgrade Required, ce qui veut dire ici mettre à jour la valeur de l'en-tête.

À quelle fréquence LinkedIn publie-t-il une nouvelle version d'API ?

Tous les mois. LinkedIn publie une nouvelle version chaque mois et prend en charge chacune « for a minimum of one (1) year », avec un journal des changements par version qui liste les ressources modifiées.

Faut-il à la fois LinkedIn-Version et X-Restli-Protocol-Version ?

Oui, sur les endpoints /rest/. La Posts API indique que toutes les API exigent Linkedin-Version au format YYYYMM et que toutes les API exigent X-Restli-Protocol-Version: 2.0.0, et une requête sans le second retombe silencieusement sur le protocole 1.0 et sa syntaxe de requête différente.

L'en-tête s'écrit-il LinkedIn-Version ou Linkedin-Version ?

La documentation de LinkedIn utilise Linkedin-Version partout, y compris à l'intérieur du message d'erreur. Les noms de champs HTTP ne sont pas sensibles à la casse, donc les deux orthographes atteignent le serveur, mais seule celle qui est documentée correspondra à une recherche dans les pages de LinkedIn.

L'en-tête Linkedin-Version s'applique-t-il aussi aux anciens endpoints v2 ?

Non, cette exigence se limite au nouveau chemin de base. Linkedin-Version est requis pour les appels sous https://api.linkedin.com/rest/, le chemin que LinkedIn a introduit en juin 2022. Les anciens endpoints sous https://api.linkedin.com/v2/, comme POST /v2/ugcPosts, ne documentent pas du tout cet en-tête, seulement X-Restli-Protocol-Version.

Le comportement d'une version de l'API LinkedIn peut-il changer après sa sortie ?

LinkedIn peut le faire, dans certaines limites. L'entreprise se réserve le droit de publier un correctif sur une version pour des raisons critiques de sécurité, de confidentialité ou de bugs, tout en qualifiant cette éventualité de minime. Le minimum d'un an de prise en charge garantit que la version reste accessible, pas que son comportement reste figé pendant cette année.

Qu'est-ce qui a changé dans l'API LinkedIn en juin 2022 ?

Les Marketing APIs de LinkedIn ont reçu ce mois-là leur première version numérotée, sous un nouveau chemin de base, https://api.linkedin.com/rest/. Tout ce qui tourne encore sur l'ancien chemin https://api.linkedin.com/v2/ date d'avant ce changement, suit des règles différentes et se passe entièrement de l'en-tête Linkedin-Version.

Pourquoi une intégration LinkedIn qui fonctionnait peut-elle tomber en panne du jour au lendemain ?

La cause silencieuse la plus courante est un en-tête de version périmé. Rien ne change dans le code, mais dès que l'année minimale de prise en charge d'une version se termine, chaque appel qui la nomme se met à renvoyer 426 NONEXISTENT_VERSION au lieu d'une réponse valide. La publication programmée y est particulièrement exposée, car l'en-tête est souvent réglé une fois pour toutes et jamais revérifié.