Richtlinien zur API-Nutzung

HubSpot überwacht aufmerksam die Nutzung unserer öffentlich-APIs, um jedem Benutzer ein erstklassiges Erlebnis zu gewährleisten. Alle Entwickler von Apps und Integrationen müssen die Richtlinie zur akzeptablen Nutzung und die API-Bedingungen von HubSpot einhalten. HubSpot behält sich das Recht vor, APIs im Laufe der Zeit zu ändern oder einzustellen. Updates werden jedoch stets im Voraus über das Änderungsprotokoll für Entwickler bereitgestellt.

Authentifizierung und Sicherheit

Für optimale Sicherheit müssen alle Apps das OAuth-Protokoll von HubSpot direkt verwenden oder sie müssen das Zugriffstoken Ihrer App verwenden, wenn Sie eine private App erstellen. Apps sind für die Speicherung von Time-to-live (TLS)-Daten und die Aktualisierung von Benutzerzugriffstoken gemäß diesem Protokoll verantwortlich. Wenn ein Zugriffstoken generiert wird, enthält es einen expires_in-Parameter, der angibt, wie lange es für API-Aufrufe verwendet werden kann, bevor es aktualisiert wird. Unauthorized (401)-Anfragen sind kein zulässiger Indikator, dass ein neues Zugriffstoken abgerufen werden muss.

Überprüfen der API-Nutzung

Private Apps

So zeigen Sie die API-Nutzung für eine private App an:

  • Klicken Sie in Ihrem HubSpot-Account in der Hauptnavigationsleiste auf das Zahnrad-Symbol.
  • Gehen Sie in der linken Seitenleiste zu Integrationen > Private Apps.
  • Klicken Sie auf den Namen der privaten App.
  • Klicken Sie auf der Seite mit den App-Details auf die Registerkarte Protokolle.
  • Überprüfen Sie die in der Tabelle aufgeführten API-Aufrufe. Sie können auch die SuchleisteFilter und Datumsauswahlen verwenden, um die angezeigten API-Aufrufe weiter zu verfeinern.

Screenshot 31.08.2023 um 16.10.28 Uhr

Erfahren Sie mehr über das Überprüfen der API-Nutzung in privaten Apps.

Öffentliche Apps, die OAuth verwenden

So zeigen Sie die API-Nutzung für eine öffentliche App an, die OAuth verwendet:

  • Gehen Sie in Ihrem Entwickler-Account in der Hauptnavigationsleiste zu Apps.
  • Klicken Sie auf den Namen der App.
  • Gehen Sie in der linken Seitenleiste zu Monitoring.
  • Verwenden Sie die Registerkarten, um verschiedene Typen von Anfragen anzuzeigen, die an oder von der App vorgenommen werden. Beim Anzeigen dieser Protokolle können Sie auf eine einzelne Anfrage klicken, um weitere Informationen anzuzeigen.
6-request_detailsErfahren Sie mehr über das Überwachen der API-Nutzung für öffentliche Apps.

Ratenbeschränkungen

Apps, die OAuth verwenden

Bei OAuth-Apps ist jeder HubSpot-Account, der Ihre App installiert, auf 100 Anfragen pro 10 Sekunden beschränkt. Dies schließt die Suche-API aus, wie im Abschnitt Sonstige Beschränkungen unten erläutert. Beschränkungen im Zusammenhang mit dem API-Add-on gelten nicht.

Private Apps

Jede private App unterliegt den Richtlinien zur API-Nutzung von HubSpot. Die Anzahl der Aufrufe, die Ihre private App durchführen kann, hängt von Ihrem Account-Abonnement ab und davon, ob Sie das API-Add-on erworben haben:

  Produktstufe Pro 10 Sekunden Pro Tag
Private Apps

(Jede Version)

Kostenlose Version und Starter

100/private App 250.000/Account
 

(Jede Version)

Pro und Enterprise

150/private App 500.000/Account
Private Apps mit API-Add-on

(Jede Version)

Kostenlose Version, Starter, Professional und Enterprise

200/private App 1.000.000/Account

Sonstige Beschränkungen

  • Sie können bis zu 100 Apps pro Entwickler-Account erstellen
  • Sie können bis zu 20 private Apps pro HubSpot-Account erstellen.
  • Sie können bis zu 1.000 Webhook-Abonnements pro App erstellen
  • Sie können bis zu 25 CRM-Erweiterungseinstellungen pro App erstellen
  • Sie können bis zu 750 Chronik-Event-Typen pro App erstellen
  • Sie können bis zu 500 Eigenschaften pro Chronik-Event-Typ erstellen
  • Bei Such-API-Endpunkten gibt es eine Ratenbeschränkung von vier Anfragen pro Sekunde pro Authentifizierungstoken
  • API-Anfragen, die von täglichen oder sekundären Limits ausgenommen sind, werden nicht in HubSpot protokolliert. Wenn Sie diese ausgenommenen Anfragen speichern möchten, müssen Sie diese Anfragen extern protokollieren.

Leistungsbeschränkungen

Weitere Informationen zu Leistungsbeschränkungen und Preisen finden Sie hier.

Fehlerantworten

Eine App oder eine Integration, die über die Ratenbeschränkungen hinausgeht, erhält eine 429-Fehlerantwort für alle nachfolgenden API-Aufrufe. Anfragen, die zu einer Fehlerantwort führen, sollten nicht mehr als 5 % Ihrer gesamten täglichen Anfragen ausmachen. Wenn Sie Ihre App im HubSpot App Marketplace listen möchten, muss sie unter 5 % liegen, um zertifiziert zu werden. 

Die 429-Antwort weist das folgende Format auf: 

//Example { "status": "error", "message": "You have reached your daily limit.", "errorType": "RATE_LIMIT", "correlationId": "c033cdaa-2c40-4a64-ae48-b4cec88dad24", "policyName": "DAILY", "requestId": "3d3e35b7-0dae-4b9f-a6e3-9c230cbcf8dd" }

 message und policyName geben an, welche Beschränkung Sie (entweder täglich oder Sekunden) erreicht haben.

Die tägliche Beschränkung wird auf der Grundlage Ihrer Zeitzoneneinstellung um Mitternacht zurückgesetzt.

In der folgenden Tabelle sind die Ratenbeschränkungen-Header aufgeführt, die in der Antwort jeder API-Anfrage an HubSpot enthalten sind, vorbehaltlich der unter der Tabelle aufgeführten Ausnahmen.

Header Beschreibung
X-HubSpot-RateLimit-Daily Die Anzahl der API-Anfragen, die pro Tag zulässig sind. Beachten Sie, dass dieser Header nicht in der Antwort auf API-Anfragen enthalten ist, die mit OAuth autorisiert wurden.
X-HubSpot-RateLimit-Daily-Remaining Die Anzahl der API-Anfragen, die für den aktuellen Tag noch erlaubt sind. Beachten Sie, dass dieser Header nicht in der Antwort auf API-Anfragen enthalten ist, die mit OAuth autorisiert wurden.
X-HubSpot-RateLimit-Interval-Milliseconds Das Zeitfenster, für das die Header X-HubSpot-RateLimit-Max und X-HubSpot-RateLimit-Remaining gelten.

Ein Wert von 10.000 wäre beispielsweise ein Fenster von 10 Sekunden.
X-HubSpot-RateLimit-Max Die Anzahl der Anfragen, die im in X-HubSpot-RateLimit-Interval-Milliseconds angegebenen Fenster zulässig sind.

Wenn beispielsweise dieser Header einen Wert von 100 hat und der Header X-HubSpot-RateLimit-Interval-Milliseconds 10.000 war, würde die erzwungene Beschränkung bei 100 Anfragen pro 10 Sekunden liegen.
X-HubSpot-RateLimit-Remaining  Die Anzahl der API-Anfragen, die für das in X-HubSpot-RateLimit-Interval-Milliseconds angegebene Fenster noch zulässig sind.

Bitte beachten:

  • Die Header X-HubSpot-RateLimit-Secondly und X-HubSpot-RateLimit-Secondly-Remaining werden weiterhin berücksichtigt und verfügen weiterhin über genaue Daten, aber die von diesen Headern referenzierten Beschränkungen werden nicht mehr durchgesetzt und diese beiden Header sollten als veraltet betrachtet werden.
  • Antworten von den Suche-API-Endpunkten enthalten keine der oben aufgeführten Ratenbeschränkungen-Header.

Mithilfe dieses Endpunkts können Sie auch die Anzahl der Aufrufe überprüfen, die während des aktuellen Tags verbraucht wurden.

Wenn Sie die TEN_SECONDLY_ROLLING-Beschränkung erreichen, sollten Sie die Anfragen, die Ihre Anwendung vornimmt, unter diese Beschränkung drosseln. Neben dem Drosseln von Anfragen sollten Sie auch folgende Vorschläge beachten (diese sind auch hilfreich, wenn Sie die tägliche Beschränkung erreichen).

Wenn Sie trotz Umsetzung dieser Vorschläge weiterhin die Aufrufbeschränkungen erreichen, bitten Sie in HubSpots Entwicklerforen nach Unterstützung. Sie sollten so viele Details wie möglich über die die von Ihnen genutzten APIs angeben: wie Sie diese verwenden und welche Beschränkung Sie erreichen.

Nach Möglichkeit Batch-APIs und Cache-Ergebnisse verwenden

Wenn Ihre Website oder App bei jedem Laden von Seiten Daten von HubSpot verwendet, sollten diese Daten im Cache gespeichert und von dort geladen werden, anstatt jedes Mal von den HubSpot-APIs angefordert zu werden. Wenn Sie wiederholt Aufrufe vornehmen, um Einstellungen von Ihrem Account für einen Batch-Auftrag abzurufen (z. B. wenn Sie Ihre Objekteigenschaften, zuständigen Mitarbeiter oder Einstellungen für ein Formular abrufen), sollten diese Einstellungen wenn möglich ebenfalls im Cache gespeichert werden.

Webhooks verwenden, um aktualisierte Daten von HubSpot zu erhalten

Wenn Sie über ein HubSpot Marketing Enterprise-Abonnement verfügen, können Sie Webhook-Aktionen in Workflows verwenden, damit Daten für Kontaktdatensätze an Ihr System gesendet werden. Webhooks können in jedem Workflow als Aktion ausgelöst werden. Daher können Sie beliebige Workflow-Startbedingungen als das Kriterium verwenden, über das Kontaktdaten an Ihr System gesendet werden. Weitere Informationen zur Verwendung von Webhooks finden Sie hier, Beispiel-Webhook-Daten finden Sie hier. Webhook-Aufrufe, die über Workflows getätigt werden, werden nicht auf die API-Ratenbeschränkung angerechnet.


War dieser Artikel hilfreich?
Dieses Formular dient dazu, Feedback zu unserer Entwicklerdokumentation zu sammeln. Wenn Sie uns Ihre Meinung zu HubSpot-Produkten mitteilen möchten, teilen Sie diese bitte im Ideenforum der Community.