Jeder /rest/-Aufruf braucht den LinkedIn-Version-Header in YYYYMM-Form

Was ist der LinkedIn-Version-Header?

Jeder Aufruf an https://api.linkedin.com/rest/ trägt einen LinkedIn-Version-Header, und LinkedIn akzeptiert dafür genau ein Wertformat: sechs Ziffern, YYYYMM. Die Versionierungsreferenz packt es in einen Satz: „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."

Der Header existiert, weil LinkedIn jeden Monat eine neue API-Version ausliefert und sich weigert zu raten, welche Sie gemeint haben. Von derselben Seite: „LinkedIn expects every versioned API call to specify a version; the latest version is not applied by default."

Eine vollständige Anfrage sieht so aus:

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

Die Versionierung kam mit einem neuen Basispfad, nicht mit einer neuen Domain. LinkedIn datiert das genau: „LinkedIn's Marketing APIs first versioned API release was June 2022 under a new base path: https://api.linkedin.com/rest/." Alles, was noch auf https://api.linkedin.com/v2/ läuft, ist älter als das Schema und verhält sich anders, worum es im letzten Abschnitt geht.

Welches Format hat der Versionswert?

YYYYMM, vierstelliges Jahr gefolgt von zweistelligem Monat, ohne Trennzeichen und ohne Tag. 202601 steht für die im Januar 2026 veröffentlichte Version. Das Beispiel, das LinkedIn für die Migration von einer Version zur nächsten gibt, ist ein einziger String-Tausch:

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

Aktuelle Werte, aus der Tabelle der Versionierungsseite übernommen:

August 2026, 202608, ist der Wert, den die Seite unter „Latest Version" führt, Stand ihrer letzten Aktualisierung am 17. August 2026. Am Format ändert sich von Monat zu Monat nichts, und genau das macht den Header sicher für ein rollendes Upgrade: ein Konfigurationswert, sechs Zeichen, ein Deploy.

Eine Ungereimtheit gehört notiert, denn sie verwirrt jeden, der auf Fehlertext matcht. Der Fehler für eine tote Version nutzt einen achtstelligen Platzhalter, „Requested version yyyymmdd is not active", während das von LinkedIn verlangte Format sechs Zeichen hat. Der Platzhalter ist die einzige Stelle, an der yyyymmdd auftaucht. Behandeln Sie ihn als Tippfehler in der Meldungsvorlage, nicht als zweites akzeptiertes Format.

Schreibt man LinkedIn-Version oder Linkedin-Version?

LinkedIns Dokumentation schreibt Linkedin-Version, mit kleinem i in der zweiten Silbe, auf jeder Seite, die den Header erwähnt. Die Versionierungsreferenz, die Images API, die Posts API, die Videos API und die Fehlerreferenz nutzen alle diese Schreibweise, und die Fehlermeldung selbst sagt „by adding the Linkedin-Version header." Der Firmenname wird auf denselben Seiten überall sonst LinkedIn geschrieben.

Feldnamen in HTTP-Headern sind nicht zwischen Groß- und Kleinschreibung unterscheidend, LinkedIn-Version, Linkedin-Version und linkedin-version erreichen auf dem Server also denselben Header. Die Schreibweise zählt aus einem engeren Grund: Wenn Sie LinkedIns Dokumentation oder eine Postman-Collection nach LinkedIn-Version durchsuchen, finden Sie nichts. Suchen Sie stattdessen nach der dokumentierten Schreibweise.

Was passiert, wenn der Header fehlt oder veraltet ist?

Zwei verschiedene Fehlschläge mit zwei verschiedenen Statuscodes, beide mit exakten Bodies dokumentiert.

Die 426 ist die interessante. HTTP 426 heißt Upgrade Required, und LinkedIn nutzt das wörtlich: Die Anfrage wurde verstanden, die genannte Version ist weg, aktualisieren Sie den Header. Es ist keine 400, keine 410 und keine 404, Fehlerbehandlungen, die nur auf 4xx-Bereiche verzweigen, leiten sie also irgendwohin, wo sie nichts nützt.

Beide Fehlschläge passieren, bevor irgendeine Geschäftslogik läuft. Ihre Nutzlast kann perfekt und Ihr Token frisch sein, und Sie bekommen trotzdem eine 400, wenn der Header fehlt. Genau das macht einen veralteten Version-Header zu einem so stillen Fehlermodus beim geplanten Veröffentlichen: In Ihrem Code ändert sich nichts, ein Abschaltdatum vergeht, und jeder Aufruf liefert plötzlich 426. Veröffentlichung, die für ein ganzes Konto über Nacht kaputtgeht, ohne Codeänderung dahinter, gehört gegen die Ursachenliste im Beitrag zu geplanten LinkedIn-Beiträgen, die nicht mehr rausgehen, geprüft.

Wie lange hält eine LinkedIn-API-Version?

Mindestens ein Jahr. Die Seite zum Rhythmus sagt es zweimal: „LinkedIn Marketing API Program publishes new versions monthly, and those versions are supported for a minimum of one (1) year" und „These API versions are supported and stable for a minimum of one year before sunset."

Das Abkündigungsbanner quer durch die Marketing-Dokumentation ist ein lebendes Beispiel für diese Uhr: „The Marketing Version 202508 (Marketing August 2025) will be sunset on August 17, 2026." Zwölf Monate und etwas, vorab angekündigt, auf jeder Seite.

Der Boden von einem Jahr kommt mit einer genannten Ausnahme. LinkedIn „reserves the right to release a patch version to any API if required for any critical security, privacy issues, or bug fixes" und nennt die Wahrscheinlichkeit minimal. Die Zusage lautet also, dass eine Version ein Jahr lang verfügbar bleibt, nicht, dass ihr Verhalten ein Jahr lang eingefroren ist.

In der Praxis heißt das Kalendereintrag statt Architekturentscheidung. Pinnen Sie die Version explizit, sehen Sie sie einmal im Jahr durch und springen Sie dabei auf die neueste, denn LinkedIns eigener Rat ist, dass die Migration auf die neueste Ihnen „the option to wait up to one year before having to migrate again" verschafft. Welche API-Oberfläche darauf sitzt und was jede Version tatsächlich regelt, behandelt der Überblick zur LinkedIn Marketing API.

Wofür ist der Header X-Restli-Protocol-Version da?

Für eine ganz andere Aufgabe, und er wird neben dem Version-Header verlangt, nicht an dessen Stelle. Die Posts API nennt beide in einem Atemzug: „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 wählt, welches API-Verhalten welchen Monats Sie bekommen. X-Restli-Protocol-Version wählt, wie Ihre URLs und Query-Parameter kodiert werden, denn LinkedIns APIs bauen auf Rest.li auf. Die Protokollseite ist beim Standard unverblümt: „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."

Der Rückfall auf 1.0 wirft keinen Fehler. Er ändert die Syntax, die der Server erwartet, und das ist schlimmer:

Eine Anfrage ohne den Protokoll-Header wird also nach Regeln geparst, gegen die Ihr Client nicht schreibt, und die entstehenden Fehler zeigen auf Ihre Parameter statt auf den fehlenden Header. LinkedIn merkt außerdem an, es „plans to deprecate protocol version 1.0 in the near future", ohne ein Datum zu nennen. Schicken Sie 2.0.0 bei jedem Aufruf, dann stellt sich die Frage nie.

Welche LinkedIn-Endpunkte brauchen den Version-Header?

Die unter /rest/. Die älteren /v2/-Endpunkte nehmen ihn nicht, und diese Trennung erklärt die meiste Verwirrung in Integrationen, die älter als 2022 sind.

Der Consumer-Leitfaden Share on LinkedIn, der weiterhin POST https://api.linkedin.com/v2/ugcPosts und POST https://api.linkedin.com/v2/assets?action=registerUpload dokumentiert, führt genau einen Pflicht-Header auf: „All requests require the following header: X-Restli-Protocol-Version: 2.0.0." Ein Version-Header taucht auf dieser Seite überhaupt nicht auf.

Jeder versionierte Bild- und Beitragsaufruf braucht beide, weshalb der Header in jeder Beispielanfrage der Anleitung dazu auftaucht, wie initializeUpload aus einer Datei eine Bild-URN macht, und weshalb die Schema-Zeilen, die Limits wie die Decke von 4.086 Zeichen für Alt-Text dokumentieren, auf versionierten Seiten leben, die sich Monat für Monat ändern. Wer ein Limit auf einer Version liest, die er nicht sendet, liest den falschen Vertrag.

Häufig gestellte Fragen

Welches Format ist für den LinkedIn-Version-Header korrekt?

Sechs Ziffern in der Form YYYYMM, etwa Linkedin-Version: 202608. LinkedIn beschreibt den Wert als entsprechend „to the documentation version you are referencing", der Header-Wert und die Dokumentationsseite, die Sie lesen, sollten also denselben Monat nennen.

Welchen Fehler liefert LinkedIn, wenn der Version-Header fehlt?

400 mit dem Code VERSION_MISSING und der Meldung „A version must be present. Please specify a version by adding the Linkedin-Version header." Die Prüfung läuft, bevor der Anfragekörper ausgewertet wird.

Was ist HTTP 426 NONEXISTENT_VERSION in der LinkedIn API?

Die Antwort auf eine abgeschaltete Version. Der dokumentierte Body ist {"status": 426, "code": "NONEXISTENT_VERSION", "message": "Requested version yyyymmdd is not active"}, und 426 ist der Status Upgrade Required, was hier heißt, den Header-Wert zu aktualisieren.

Wie oft veröffentlicht LinkedIn eine neue API-Version?

Monatlich. LinkedIn veröffentlicht jeden Monat eine neue Version und unterstützt jede „for a minimum of one (1) year", mit einem Changelog pro Version, der aufführt, welche Ressourcen sich geändert haben.

Brauchen Sie sowohl LinkedIn-Version als auch X-Restli-Protocol-Version?

Ja, an /rest/-Endpunkten. Die Posts API hält fest, dass alle APIs Linkedin-Version im Format YYYYMM verlangen und alle APIs X-Restli-Protocol-Version: 2.0.0, und eine Anfrage ohne den zweiten fällt still auf Protokoll 1.0 mit seiner abweichenden Query-Syntax zurück.

Schreibt man den Header LinkedIn-Version oder Linkedin-Version?

LinkedIns Dokumentation nutzt überall Linkedin-Version, auch innerhalb der Fehlermeldung. HTTP-Feldnamen unterscheiden nicht zwischen Groß- und Kleinschreibung, beide Schreibweisen erreichen den Server also, aber nur die dokumentierte trifft eine Suche in LinkedIns eigenen Seiten.

Gilt der Linkedin-Version-Header auch für die älteren v2-Endpunkte?

Nein, diese Pflicht gilt nur für den neuen Basispfad. Linkedin-Version wird bei Aufrufen unter https://api.linkedin.com/rest/ verlangt, dem Pfad, den LinkedIn im Juni 2022 eingeführt hat. Die älteren Endpunkte unter https://api.linkedin.com/v2/, etwa POST /v2/ugcPosts, dokumentieren diesen Header gar nicht, nur X-Restli-Protocol-Version.

Kann sich das Verhalten einer LinkedIn-API-Version nach der Veröffentlichung noch ändern?

LinkedIn kann das, innerhalb gewisser Grenzen. Das Unternehmen behält sich vor, für kritische Sicherheits-, Datenschutz- oder Bugfixes einen Patch auf eine Version zu veröffentlichen, hält das aber selbst für unwahrscheinlich. Die Mindestlaufzeit von einem Jahr garantiert, dass die Version erreichbar bleibt, nicht dass sich ihr Verhalten in dieser Zeit nicht ändert.

Was hat sich im Juni 2022 an der LinkedIn-API geändert?

LinkedIns Marketing APIs erhielten in diesem Monat ihre erste versionierte Freigabe, unter einem neuen Basispfad, https://api.linkedin.com/rest/. Alles, was noch auf dem älteren Pfad https://api.linkedin.com/v2/ läuft, stammt aus der Zeit davor, folgt anderen Regeln und kommt ganz ohne den Linkedin-Version-Header aus.

Warum kann eine funktionierende LinkedIn-Integration über Nacht ausfallen?

Die häufigste stille Ursache ist ein veralteter Version-Header. Am Code ändert sich nichts, aber sobald die einjährige Mindestlaufzeit einer Version abläuft, liefert jeder Aufruf mit dieser Version 426 NONEXISTENT_VERSION statt eines Ergebnisses. Geplante Veröffentlichungen sind besonders anfällig, weil der Header oft einmal gesetzt und danach nie wieder geprüft wird.