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 Zeitverlauf zu ändern oder einzustellen. In einem solchen Fall informieren wir Entwickler jedoch stets über unser Änderungsprotokoll im Voraus.

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 und Apps, die OAuth verwenden

Verwenden Sie API-Aufrufüberwachung in den Einstellungen der App.

Integrationen, die API-Schlüssel verwenden

Bitte beachten: seit dem 30. November 2022 sind HubSpot-API-Schlüssel veraltet und werden nicht mehr unterstützt. Die fortgesetzte Verwendung von HubSpot API-Schlüsseln stellt ein Sicherheitsrisiko für Ihren Account und Ihre Daten dar. Während dieser Phase bis zur endgültigen Einstellung kann HubSpot Ihren Schlüssel jederzeit deaktivieren.

Sie sollten sich stattdessen mit einem Zugriffstoken für private Apps oder über OAuth authentifizieren. Erfahren Sie mehr über diese Änderung und wie Sie eine API-Schlüssel-Integration migrieren, um stattdessen eine private App zu verwenden.

Um zu überprüfen, wie viele API-Aufrufe für den aktuellen Tag durchgeführt wurden und wann die Beschränkung zurückgesetzt wird, führen Sie eine GET-Anfrage an /integrations/v1/limit/daily? hapikey =key_value durch, wobei key_value der HubSpot-API-Schlüssel des Accounts ist. Der aktuelle Tag wird von Mitternacht bis Mitternacht basierend auf den Zeitzoneneinstellungen des verknüpften Accounts gemessen. Aufrufe an diesen Endpunkt werden auf Ihre täglichen API-Beschränkungen angerechnet.

Die von diesem Endpunkt zurückgegebenen Daten werden fünf Minuten lang im Cache gespeichert. Überprüfen Sie die Felder fetchStatus und collectedAt in der Antwort, um zu ermitteln, ob sie aus dem Cache stammen.

Beispiel-Antwort:

// [ { "name": "api-calls-daily", "usageLimit": 1000000, "currentUsage": 31779, "collectedAt": 1560189939285, "fetchStatus": "SUCCESS", "resetsAt": 1560204000000 } ]

Das resetsAt-Feld ist ein Unix-Zeitstempel (in Millisekunden) des Zeitpunkts, an dem die Beschränkung zurückgesetzt wird. Die Beschränkung wird basierend auf der Zeitzoneneinstellung des Accounts um Mitternacht zurückgesetzt.

Beispiel-Cache-Antwort:

// [ { "name": "api-calls-daily", "usageLimit": 1000000, "currentUsage": 31779, "collectedAt": 1560189939285, "fetchStatus": "CACHED", "resetsAt": 1560204000000 } ]

Wenn die Antwort von Cache stammt, hat fetchStatus den Wert "CACHED" und collectedAt ist ein Unix-Zeitstempel in Millisekunden, der angibt, wann der Cache zuletzt aktualisiert wurde.

Ratenbeschränkungen

Apps, die OAuth verwenden

Apps, die OAuth verwenden, unterliegen nur einer Beschränkung von 100 Anfragen pro 10 Sekunden (mit Ausnahme der Such-API, wie unter „Sonstige Beschränkungen” aufgeführt). 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

 

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 in unserem 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.

Jede API-Anfrage enthält die folgenden Ratenbeschränkungen-Header in der Antwort. HINWEIS: Die Header Daily und Daily-Remaining werden bei Anfragen, die über OAuth autorisiert wurden, nicht berücksichtigt.

Header Beschreibung
X-HubSpot-RateLimit-Daily Die Anzahl der API-Anfragen, die pro Tag zulässig sind.
X-HubSpot-RateLimit-Daily-Remaining Die Anzahl der API-Anfragen, die für den aktuellen Tag noch erlaubt sind.
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.

Hinweis: 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.

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, teilen Sie uns dies in unserem Entwicklerforen mit. Wir möchten so viele Details wie möglich über die APIs, die Sie verwenden, in Erfahrung bringen: wie Sie diese verwenden und welche Beschränkung Sie erreichen.

Daten für wiederholte Anrufe im Cache speichern

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.

Batch-APIs verwenden, wenn möglich

Wenn Sie nicht mit zeitintensiven Daten arbeiten, kann das Gruppieren von Updates in regelmäßige Batches statt jeweils einzelner Updates eine effektive Maßnahme sein. 

Wenn Sie mit CRM-Objekten (Kontakte, Unternehmen, Deals usw.) arbeiten, stehen Batch-Methoden zur Verfügung.

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.

 

Leistungsbeschränkungen

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

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

Verwandte Dokumente

Überprüfen der API-Nutzung innerhalb der App