Handling errors

Sofern nicht anders angegeben, geben die meisten HubSpot-Endpunkte eine „200 OK“-Antwort bei einem Erfolg zurück. Bei allen Endpunkten, die einen anderen Statuscode zurückgeben, wird die zurückgegebene Antwort in ihrer Dokumentation erläutert.

Darüber hinaus hat HubSpot mehrere Fehlerantworten, die häufig bei mehreren APIs auftreten:

  • 401 Unauthorized: Wird zurückgegeben, wenn die angegebene Authentifizierung ungültig ist. Weitere Informationen zur Authentifizierung von API-Anfragen finden Sie in unserer  Übersicht über die Authentifizierung.
  • 403 Forbidden: Wird zurückgegeben, wenn die Authentifizierung nicht die erforderlichen Berechtigungen hat, um auf die spezifische URL zuzugreifen. Ein OAuth-Token, das nur Content-Zugriff hat, würde eine 403-Meldung erhalten, wenn es auf die Deals-API zugreift (die Zugriff auf Kontakte erfordert). Wenn Sie bestätigt haben, dass Ihr API-Schlüssel oder Ihre private App über die erforderlichen Berechtigungen verfügt, wenden Sie sich bitte an den HubSpot-Support, um Hilfe zu erhalten. 
  • 429 Too many requests: Wird zurückgegeben, wenn Ihr Account oder Ihre App über den API-Ratenbegrenzungen liegt. Hier finden Sie Vorschläge, wir Sie mit diesen Limits umgehen.
  • 477 Migration in Progress: Wird zurückgegeben, wenn ein HubSpot-Account gerade zwischen Datenhosting-Standorten migriert wird. HubSpot gibt einen Retry-After-Antwort-Header zurück, der angibt, wie viele Sekunden gewartet werden muss, bevor die Anfrage erneut versucht wird (in der Regel bis zu 24 Stunden). 
  • 502/504 timeouts: Wird zurückgegeben, wenn die Verarbeitungslimits von HubSpot eingehalten wurden. Diese Limits sollen verhindern, dass ein einzelner Client Leistungseinbußen verursacht. Diese Timeout-Antworten treten auf, wenn Sie eine große Anzahl von Anfragen über einen längeren Zeitraum vornehmen. Wenn Sie eine dieser Antworten erhalten, sollten Sie Ihre Anfragen für einige Sekunden pausieren und es dann erneut versuchen.
  • 503 service temporarily unavailable: Wird zurückgegeben, wenn HubSpot vorübergehend nicht verfügbar ist. Wenn Sie diese Antwort erhalten, sollten Sie Ihre Anfragen für einige Sekunden pausieren und es dann erneut versuchen.
  • 521 web server is down: Wird zurückgegeben, wenn der HubSpot-Server ausgefallen ist, sollte dies ein temporäres Problem sein. Wenn Sie diese Antwort erhalten, sollten Sie Ihre Anfragen für einige Sekunden pausieren und es dann erneut versuchen.
  • 522 connnection timed out: Wird zurückgegeben, wenn die Verbindung zwischen HubSpot und Ihrer Anwendung abgelaufen ist. Wenn Sie diese Antwort erhalten haben, wenden Sie sich bitte an den HubSpot-Support, um Hilfe zu erhalten. 
  • 523 origin is unreachable: Wird zurückgegeben, wenn HubSpot Ihre Anwendung nicht kontaktieren kann. Wenn Sie diese Antwort erhalten, sollten Sie Ihre Anfragen für einige Sekunden pausieren und es dann erneut versuchen. 
  • 524 timeout: wird zurückgegeben, wenn eine Antwort nicht innerhalb von 100 Sekunden empfangen wird. Dies kann vorkommen, wenn der HubSpot-Server überlastet ist, z. B. bei einer großen Datenabfrage. Wenn Sie diese Antwort erhalten, sollten Sie Ihre Anfragen für einige Sekunden pausieren und es dann erneut versuchen.
  • 525/526 SSL issues: Wird zurückgegeben, wenn das SSL-Zertifikat ungültig ist oder der SSL-Handshake fehlschlägt. Wenn Sie diese Antwort erhalten haben, wenden Sie sich bitte an den HubSpot-Support, um Hilfe zu erhalten. 

Neben diesen allgemeinen Fehlern sind die Antworten auf HubSpot-Fehler als menschenlesbare Inhalte gedacht. Die meisten Endpunkte geben keine Fehlercodes, sondern eine JSON-formatierte Antwort mit Details zum Fehler zurück. Weitere Details zu endpunktspezifischen Fehlern finden Sie auf den Dokumentationsseiten für den Endpunkt.

Bitte beachten: Die folgenden Felder in der Beispielantwort sollten bei jeder Fehleranalyse als optional behandelt werden. Die spezifischen enthaltenen Felder können zwischen verschiedenen APIs variieren, so dass bei der Fehleranalyse berücksichtigt werden sollte, dass bestimmte Felder in der Antwort fehlen.

// Structure of an example error from HubSpot { "status": "error", "message": "This will be a human readable message with details about the error.", "errors": [ { "message": "This will be a message with additional details about the error", "in": "name" } ], "category": "VALIDATION_ERROR", "correlationId": "a43683b0-5717-4ceb-80b4-104d02915d8c" }

Erneute Versuche

Wenn Ihre App oder Ihre Integration einen Endpunkt bereitstellt, den HubSpot dann aufruft, z. B. Webhook-Abonnements, führen alle Fehler, die Ihr Endpunkt verursacht, dazu, dass HubSpot die Anfrage erneut versucht. 

Webhooks

Wenn bei Ihrem Service Probleme bei der Datenverarbeitung zu irgendeinem Zeitpunkt auftreten, versucht HubSpot, diese Benachrichtigungen bis zu 10 Mal erneut zu senden.

HubSpot versucht es in den folgenden Fällen erneut:

  • Verbindung fehlgeschlagen: HubSpot kann eine http-Verbindung mit der angegebenen Webhook-URL nicht öffnen.
  • Timeout: Ihr Service benötigt länger als 5 Sekunden, um eine Antwort zurück an einen Batch an Benachrichtigungen zu senden
  • Fehlercodes: Ihr Service antwortet mit einem beliebigen HTTP-Statuscode (4xx oder 5xx)
Workflows werden nach Erhalt der Antwortstatuscodes der 4xx-Serie nicht erneut versucht. Eine Ausnahme von dieser Regel sind 429-Ratenbegrenzungsfehler. Workflows werden nach Erhalt einer 429-Antwort automatisch wiederholt und respektieren den Retry-After -Header, falls vorhanden. Beachten Sie, dass der Retry-After-Wert in Millisekunden angegeben wird.

Benachrichtigungen werden bis zu 10 Mal erneut versucht. Diese erneuten Versuche werden mit wechselnden Verzögerungen zwischen den Anfragen über die nächsten 24 Stunden verteilt. Bei einzelnen Benachrichtigungen wird etwas Randomisierung angewendet, um zu verhindern, dass eine große Anzahl erneuter Versuche zum exakt gleichen Zeitpunkt gleichzeitig fehlschlägt.

Workflow-Aktionen mit benutzerdefiniertem Code

Wenn Sie eine benutzerdefinierte Code-Aktion in einem Workflow erstellen und ein API-Aufruf in Ihrer Aktion aufgrund eines Ratenbegrenzungsfehlers oder eines 429- oder 5xx-Fehlers von axios oder @hubspot/api-client fehlschlägt, versucht HubSpot eine Minute nach dem Fehler bis zu drei Tage lang erneut, Ihre Aktion auszuführen. Nachfolgende fehlgeschlagene Webhooks werden in größeren Intervallen mit einer maximalen Lücke von acht Stunden versucht, erneut auszuführen.

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.