Handling errors

Sauf mention contraire, la plupart des points de terminaison de HubSpot renverront une réponse OK 200 en cas de réussite. Tous les points de terminaison qui renvoient un code de statut différent indiqueront la réponse renvoyée dans leurs documentations respectives.

En outre, HubSpot propose plusieurs réponses d'erreur communes à plusieurs API :

  • 401 Unauthorized : renvoyée lorsque l'authentification est non valide. Consultez notre présentation de l'authentification pour plus de détails sur l'authentification des demandes d'API.
  • 403 Forbidden : renvoyée lorsque l'authentification fournie ne possède pas les autorisations nécessaires pour accéder à l'URL spécifique. Par exemple, un jeton OAuth qui dispose uniquement d'un accès au contenu recevra une réponse 403 lors de l'accès à l'API de transactions (qui nécessite l'accès aux contacts). Si vous avez confirmé que votre clé API ou votre application privée dispose des autorisations nécessaires, veuillez contacter le support HubSpot pour obtenir de l'aide. 
  • 429 Too many requests : renvoyée lorsque votre compte ou application dépasse ses limites quant aux API. Pour en savoir plus sur ces limites, cliquez ici.
  • 477 Migration in Progress : renvoyé lorsqu'un compte HubSpot est en cours de migration entre différents sites d'hébergement de données. HubSpot renverra un en-tête de réponse Retry-After indiquant le nombre de secondes à attendre avant de retenter la demande (généralement jusqu'à 24 heures). 
  • 502/504 timeouts : renvoyée lorsque les limites de traitement de HubSpot ont été atteintes. Ces limites de traitement existent afin d'empêcher une dégradation des performances pour un client. Les réponses d'expiration se produisent lorsque vous effectuez un grand nombre de demandes sur une période prolongée. Si vous obtenez l'une de ces réponses, vous devez suspendre vos demandes pendant quelques secondes, puis réessayer.
  • 503 service temporarily unavailable : renvoyée lorsque HubSpot est temporairement indisponible. Si vous obtenez cette réponse, vous devez suspendre vos demandes pendant quelques secondes, puis réessayer.
  • 521 web server is down : renvoyée lorsque le serveur de HubSpot est en panne, cela devrait être un problème temporaire. Si vous obtenez cette réponse, vous devez suspendre vos demandes pendant quelques secondes, puis réessayer.
  • 522 connection timed out : renvoyée lorsque la connexion entre HubSpot et votre application a expiré. Si vous avez reçu cette réponse, veuillez contacter le support HubSpot pour obtenir de l'aide. 
  • 523 origin is unreachable : renvoyée lorsque HubSpot n'est pas en mesure de contacter votre application. Si vous obtenez cette réponse, vous devez suspendre vos demandes pendant quelques secondes, puis réessayer. 
  • 524 timeout : renvoyée lorsqu'une réponse n'est pas reçue dans les 100 secondes. Cela peut se produire lorsque le serveur du HubSpot est surchargé, par exemple avec une requête de données volumineuse. Si vous obtenez cette réponse, vous devez suspendre vos demandes pendant quelques secondes, puis réessayer.
  • 525/526 SSL issues : renvoyée lorsque le certificat SSL n'est pas valide ou que la liaison SSL échoue. Si vous avez reçu cette réponse, veuillez contacter le support HubSpot pour obtenir de l'aide. 

Outre ces erreurs générales, les réponses d'erreur de HubSpot sont conçues pour être concises et lisibles. La plupart des points de terminaison ne renvoient pas les codes d'erreur, mais une réponse JSON avec des détails sur l'erreur. Plus de détails concernant les erreurs spécifiques à chaque point de terminaison sont disponibles sur les pages de documentation des points de terminaison.

Remarque : Les champs dans l'exemple de réponse ci-dessous doivent être traités comme facultatifs dans n'importe quelle analyse d'erreur. Les champs spécifiques inclus peuvent varier selon les API. Toute analyse d'erreur doit permettre l'absence de champs spécifiques de la réponse.

// 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" }

Nouvelles tentatives

Si votre application ou intégration fournit un point de terminaison que HubSpot appellera, comme des abonnements webhook, toute erreur que votre point de terminaison lance amènera HubSpot à réessayer la requête. 

Webhooks

Si votre service rencontre des problèmes de traitement des notifications, HubSpot tentera d'envoyer à nouveau les notifications jusqu'à 10 fois.

HubSpot procèdera à de nouvelles tentatives dans les cas suivants :

  • La connexion a échoué : HubSpot ne parvient pas à ouvrir une connexion HTTP de l'URL de webhook fournie.
  • Expiration : votre service prend plus de 5 secondes pour renvoyer une réponse à un lot de notifications.
  • Codes d'erreur : votre service répond avec un code de statut HTTP (4xx ou 5xx).
Les workflows ne seront pas réexécutés après la réception de codes de statut de réponse 4XX. Une exception à cette règle est l'erreur 429 de limite de débit ; les workflows seront automatiquement réexécutés après la réception d'une réponse 429 et respecteront l'en-tête Retry-After, le cas échéant. Notez que la valeur Retry-After est exprimée en millisecondes.

Les notifications seront renvoyées jusqu'à 10 fois. Ces tentatives seront réparties sur les 24 heures suivantes, avec des délais différents entre les demandes. Afin d'éviter la récupération au même moment d'un grand nombre d'échecs concomitants, les notifications individuelles feront l'objet d'une distribution au hasard.

Actions de workflow à code personnalisé

Si vous créez une action de code personnalisé dans un workflow et si un appel d'API échoue en raison d'une erreur de limite ou d'une erreur 429 ou 5XX d'axios ou de @hubspot/api-client, HubSpot tentera à nouveau d'exécuter votre action pendant trois jours maximum, en commençant une minute après l'échec. Les tentatives après les échecs ultérieurs seront effectuées à intervalles croissants, avec un écart maximum de huit heures entre les tentatives.

Cet article vous a-t-il été utile ?
Ce formulaire est destiné à recueillir les avis sur la documentation pour les développeurs. Si vous souhaitez faire part de votre avis sur les produits HubSpot, veuillez le partager sur le forum des idéesde la communauté.