HubSpot API 2026: Neue Versionierung und Rate Limits

Der Umbruch: Warum HubSpot die Versionierung seiner APIs neu aufsetzt

HubSpot vollzieht 2026 einen der grundlegendsten Schnitte in der Geschichte seiner Plattform-APIs: den Wechsel von einer klassischen, semantischen Versionierung (v1, v2, v3, v4) zu einem datumsbasierten Schema. Der Hintergrund ist laut HubSpot ein strukturelles Problem, das viele API-Anbieter kennen: Es war für Entwickler kaum vorhersehbar, welche Version aktuell empfohlen wird, wann eine ältere Version wegfällt und wie viel Vorlauf für eine Migration bleibt. Breaking Changes wurden in der Vergangenheit teils mit nur 90 Tagen Vorlaufzeit angekündigt – ein Zeitraum, der für komplexe CRM-Integrationen mit mehreren nachgelagerten Systemen oft zu knapp ist.

Mit der neuen Versionierung, den aktualisierten Rate-Limit-Strukturen und der endgültigen Abschaltung älterer Endpoints wie der Contact Lists API v1 verändert sich 2026 gleich an mehreren Stellen, wie Integrationen gegen die HubSpot-API entwickelt, betrieben und gewartet werden müssen. Für Entwickler und Integratoren ergeben sich daraus sowohl planbarere Prozesse als auch konkreter Handlungsbedarf an bestehendem Code.

Von v1–v4 zu /YYYY-MM/: So funktioniert die neue Versionierung

Kernstück der Umstellung ist der Wechsel von Pfaden wie /crm/v3/objects/contacts zu datumsbasierten Pfaden im Format /crm/objects/2026-03/contacts. Die erste generell verfügbare (GA) Version nach diesem Schema ist /2026-03/, veröffentlicht im März 2026; die nächste reguläre Version folgt im September 2026 als /2026-09/. Der Name einer Version entspricht damit direkt dem Release-Fenster, in dem sie erschienen ist.

Wesentliche Eigenschaften des neuen Modells:

• Feste Release-Kadenz: Zwei GA-Versionen pro Jahr, jeweils im März und September, synchron zum allgemeinen Plattform-Release-Zyklus von HubSpot.
• Unveränderlichkeit (Immutability): Ist eine Version einmal veröffentlicht, ändert sich ihr Verhalten nicht mehr rückwirkend. Breaking Changes werden ausschließlich in neuen, separat benannten Versionen ausgeliefert, nie nachträglich in eine bestehende Version eingespielt.
• Beta-Versionen folgen der Konvention /YYYY-MM-beta/ und erscheinen etwa sechs Monate vor der zugehörigen GA-Version. Sie verlieren rund acht Wochen nach dem GA-Release ihren Support-Status.
• Explizite Versionsbindung: Anders als bei manchen impliziten „latest"-Verhalten früherer API-Generationen müssen Integrationen ihre Zielversion künftig explizit im Pfad angeben.

Die Umstellung betrifft nicht nur die REST-APIs selbst, sondern auch die Developer-Plattform für Apps und Projects: Mit Version 2026.03, veröffentlicht am 30. März 2026, erhielt erstmals auch die App-Entwicklungsumgebung eine datumsbasierte Versionsnummer. Eine sichtbare technische Änderung in dieser Version betrifft das Format von App-Funktionen: Statt einer einzelnen serverless.json-Datei kommt nun das granularere *-hsmeta.json-Format zum Einsatz, bei dem jede Funktion in einer eigenen Datei definiert wird. Projekte, die noch auf der älteren 2025.1-Struktur basierten, ließen sich zuvor nicht ohne Weiteres auf neuere Plattformversionen migrieren – mit 2026.03 wurde dieser Migrationspfad geöffnet.

Lebenszyklus und Support-Fenster: Was Entwickler einplanen müssen

Für jede date-based Version gilt ein zweistufiges Support-Modell mit insgesamt 18 Monaten Laufzeit:

• Current (Monate 1–6): Aktive Pflege inklusive Bugfixes und nicht-brechender Verbesserungen.
• Supported (Monate 7–18): Nur noch kritische Fehlerbehebungen, etwa bei Sicherheitslücken oder Stabilitätsproblemen.
• Unsupported (ab Monat 19): Keine Garantie mehr für Stabilität, Fixes oder fortgesetzte Funktionsfähigkeit. Wichtig dabei: Der Support-Status gilt jeweils für die gesamte Versionsfamilie, nicht für einzelne Endpoints innerhalb dieser Version.

Für bestehenden Code bedeutet das konkret: Die aktuellen v4-Endpoints bleiben nach HubSpots eigenen Angaben voraussichtlich bis März 2027 nutzbar, ältere v3-Endpoints sollen mit dem „Spring Spotlight"-Release 2027 in den unsupported-Status übergehen. Eine feste, sofortige Abschaltung findet für diese älteren, semantisch versionierten APIs zunächst nicht statt – sie laufen parallel zu den neuen datumsbasierten Versionen weiter, allerdings ohne Weiterentwicklung.

Strenger geregelt ist der Umgang mit datumsbasierten Versionen im Marketplace-Kontext: Öffentlich über den HubSpot Marketplace vertriebene Apps müssen künftig auf eine konkrete, innerhalb des aktuellen Support-Fensters liegende date-based Version festgelegt sein, um zertifiziert beziehungsweise rezertifiziert zu werden. Wer eine Marketplace-App betreibt, kommt an einer aktiven Versionsstrategie damit nicht vorbei.

Eine weitere, für Integratoren relevante Änderung ist ab der Version /2026-09/ (Start: 8. September 2026) angekündigt: HubSpot will ab diesem Zeitpunkt administratorseitig konfigurierte Validierungsregeln auf allen schreibenden CRM-API-Pfaden durchsetzen. Schreibzugriffe über die API unterliegen damit potenziell denselben Validierungslogiken, die bislang primär im UI-Kontext galten – ein Punkt, der bei automatisierten Massenimporten oder Synchronisationsjobs zu neuen Fehlerfällen führen kann, wenn Datensätze nicht den im Portal hinterlegten Validierungsregeln entsprechen.

Rate Limits 2026: Was sich bei Burst- und Tageslimits ändert

Parallel zur Versionsumstellung gelten 2026 weiterhin gestaffelte Rate Limits, die sich nach App-Typ und Vertriebsmodell richten. Für privat verteilte Apps (private apps) auf den aktuellen Plattformversionen 2025.2 und 2026.03 gilt tarifabhängig:

• Free/Starter: 100 Requests pro 10 Sekunden je App, 250.000 Requests pro Tag je Account.
• Professional: 190 Requests pro 10 Sekunden, 625.000 Requests pro Tag.
• Enterprise: 190 Requests pro 10 Sekunden, bis zu 1.000.000 Requests pro Tag.
• Mit dem optionalen API-Limit-Increase-Add-on lassen sich Burst-Limits weiter anheben; laut HubSpot-Dokumentation ist dieses Add-on jedoch maximal zweimal pro Account aktivierbar und wirkt ausschließlich bei privat verteilten Apps.

Für öffentlich über OAuth verteilte Apps, etwa Marketplace-Integrationen, gilt ein separates Limit: Jeder Account, der eine solche App installiert, ist unabhängig vom eigenen HubSpot-Tarif auf rund 110 Requests pro 10 Sekunden begrenzt. Das API-Limit-Increase-Add-on wirkt hier nicht.

Deutlich enger gefasst sind die Limits für Such-Endpoints (CRM Search API): Hier gilt ein Limit im Bereich von 4 bis 5 Requests pro Sekunde je Account beziehungsweise Token – HubSpot hat diesen Wert in der Vergangenheit bereits leicht angehoben, er bleibt aber der mit Abstand restriktivste Grenzwert im gesamten API-Portfolio. Integrationen, die Suchanfragen für Massenabgleiche oder Deduplizierung nutzen, sollten dies bei der Lastverteilung explizit berücksichtigen und nicht mit den allgemeinen Burst-Limits verwechseln.

Wird ein Limit überschritten, antwortet die API mit dem HTTP-Statuscode 429, bis das jeweilige Zeitfenster (10 Sekunden beziehungsweise ein Kalendertag) wieder zurückgesetzt ist. Response-Header zu verbleibenden Kontingenten werden bei den regulären Endpoints mitgeliefert, bei Such-Endpoints laut Dokumentation jedoch nicht – ein Detail, das robuste Retry- und Backoff-Strategien in der Praxis erschwert und dazu zwingt, Limits eher konservativ und clientseitig selbst zu überwachen.

Abkündigung der Contact Lists API v1 zum 30. April 2026

Neben Versionierung und Rate Limits betrifft eine dritte Änderung unmittelbar bestehende Integrationen: die endgültige Abschaltung der Contact Lists API v1. Ursprünglich für den 30. September 2025 angekündigt, hatte HubSpot die Frist bereits im September 2025 auf den 30. April 2026 verschoben, um Integratoren mehr Migrationszeit einzuräumen.

Ab diesem Datum werden alle bis auf drei Endpoints der v1-API mit HTTP 404 antworten. Die verbleibenden drei Endpoints funktionieren zwar technisch weiter, liefern aber keine Listenmitgliedschaften mehr zurück:

• GET /contacts/v1/lists/all/contacts/all
• GET /contacts/v1/lists/recently_updated/contacts/recent
• GET /contacts/v1/lists/all/contacts/recent

Für alle Anwendungsfälle rund um Listenerstellung, -aktualisierung, -abfrage und Mitgliedschaftsverwaltung ist eine Migration auf die Lists v3 API erforderlich. HubSpot stellt dafür einen dedizierten Migrationsleitfaden bereit, der die funktionale Entsprechung der alten v1-Endpoints in der v3-API dokumentiert. Wichtig für die Priorisierung: Betroffen sind nicht nur aktiv genutzte Anwendungen, sondern häufig auch in Vergessenheit geratene Hintergrundjobs, Middleware-Verbindungen oder No-Code-Automatisierungen (etwa in Workflow-Tools von Drittanbietern), die intern noch gegen v1-Endpoints laufen.

Die Contact Lists API v1 steht dabei nicht isoliert da: Für 2026 sind weitere Abkündigungen älterer Schnittstellen terminiert, etwa die Pipelines API v1 (Sunset zum 4. Dezember 2026) sowie das Ende des Renderings sogenannter Legacy-CRM-Cards auf Basis der älteren CRM Extensions API zum 31. Oktober 2026. Wer Integrationen betreut, die vor mehreren Jahren aufgesetzt wurden, sollte diese Liste an Enddaten in der Roadmap-Planung berücksichtigen, statt jede Abkündigung einzeln und reaktiv zu behandeln.

Migrationsschritte für Entwickler und Integratoren

HubSpot selbst empfiehlt für die Umstellung ein strukturiertes, mehrstufiges Vorgehen, das sich unabhängig von der Größe der Integration anwenden lässt:

1. Vollständige Bestandsaufnahme: Alle Stellen identifizieren, an denen Code gegen die HubSpot-API kommuniziert – inklusive Backend-Services, Webhooks, geplanter Batch-Jobs und einmaliger Utility-Skripte, die im Tagesgeschäft leicht übersehen werden. 2. Versionsklassifizierung: Für jeden identifizierten Endpoint dokumentieren, ob er über eine semantische Version (v1–v4) oder bereits über eine datumsbasierte Version (/YYYY-MM/) angesprochen wird. 3. Explizite Versionsbindung: Integrationen so konfigurieren, dass sie eine konkrete Version referenzieren, statt sich auf implizites Standardverhalten zu verlassen – das reduziert das Risiko unerwarteter Änderungen bei künftigen Releases. 4. Paralleltest neuer Versionen: Vor einer vollständigen Umstellung empfiehlt sich, für einen Teil des Traffics parallel gegen die neue datumsbasierte Version zu testen und Antworten sowie Fehlerverhalten mit der bisherigen Version abzugleichen. 5. SDKs aktualisieren: HubSpots offizielle Client-SDKs wurden im Zuge der Umstellung überarbeitet, um datumsbasierte Versionen korrekt abzubilden. Wer über die offiziellen SDKs statt über direkte HTTP-Aufrufe integriert, sollte auf eine aktuelle SDK-Version prüfen, bevor Legacy-Versionen unsupported werden. 6. Monitoring des Changelogs: Da Breaking Changes nun ausschließlich mit neuen Versionen ausgeliefert werden, lohnt sich ein regelmäßiger Blick in den offiziellen HubSpot-Changelog, um Beta-Ankündigungen frühzeitig zu erfassen und Migrationsfenster aktiv statt reaktiv zu nutzen.

Für Rate Limits gilt ergänzend: Integrationen mit hohem Anfragevolumen sollten clientseitige Warteschlangen beziehungsweise Backoff-Mechanismen implementieren, die zwischen regulären Endpoints und den deutlich enger limitierten Such-Endpoints unterscheiden, statt ein einheitliches globales Limit anzunehmen.

Fazit

Die Umstellung auf datumsbasierte API-Versionen ist der strukturell bedeutendste Schritt in HubSpots API-Strategie seit Einführung der v3-Generation. Für Entwickler und Integratoren bedeutet das mittelfristig mehr Planungssicherheit durch feste, im Voraus bekannte Release- und Sunset-Termine – kurzfristig aber auch konkreten Aufwand: eine saubere Bestandsaufnahme aller Endpoint-Aufrufe, die explizite Versionsbindung im Code sowie die fristgerechte Migration weg von auslaufenden Schnittstellen wie der Contact Lists API v1. Wer diese Schritte bis zu den jeweiligen Stichtagen 2026 nachvollzieht, reduziert das Risiko unerwarteter Ausfälle deutlich – unabhängig davon, ob die eigene Integration über wenige Dutzend oder mehrere Millionen API-Aufrufe pro Tag läuft.