Dernière modification : 12 septembre 2025
// translate-ignore “Découvrez comment gérer les erreurs d’API courantes lors du développement avec les API HubSpot.”; 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 :
  • 207 Multi-Status : renvoyée lorsqu’il existe différents statuts (par exemple : erreurs et réussites), ce qui se produit lorsque vous avez activé la gestion des erreurs à statuts multiples pour les points de terminaison de création par lots d’API d’objets.
  • 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é d’API ou votre application privée dispose des autorisations nécessaires, veuillez contacter le support HubSpot pour obtenir de l’aide.
  • 423 Locked : renvoyée lors d’une tentative de synchronisation d’un grand volume de données (par exemple, l’insertion de milliers de fiches d’informations d’entreprise dans un laps de temps très court). Le verrouillage durera 2 secondes. Si vous recevez une erreur 423, vous devez donc prévoir un délai d’au moins 2 secondes entre vos demandes d’API.
  • 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ée 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 connnection 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.
  • Pour les API d’objets CRM, les réponses d’erreur incluront les champs détaillés message, code, et context, qui fourniront des informations supplémentaires sur les propriétés requises qui n’ont pas été incluses dans votre requête, ainsi que sur tout problème lié à des propriétés mal formées dans votre requête.
  • Plus de détails concernant les erreurs spécifiques à chaque point de terminaison sont disponibles sur les pages de documentation des points de terminaison.
// Structure of an example error from HubSpot
{
  "status": "error",
  "message": "This will be a human readable message with details about the error.",
  "errors": [
    {
      "message": "discount was not a valid number",
      "code": "INVALID_INTEGER",
      "context": {
        "propertyName": ["discount"]
      }
    }
  ],
  "category": "VALIDATION_ERROR",
  "correlationId": "a43683b0-5717-4ceb-80b4-104d02915d8c"
}

​
Erreurs à statuts multiples

Pour les points de terminaison de création par lots d’API d’objets’, vous pouvez activer des réponses à statuts multiples qui incluent des échecs partiels. Cela signifie que la réponse indiquera quelles fiches d’informations ont été créées et lesquelles ne l’ont pas été. Pour ce faire, incluez une valeur unique objectWriteTraceId pour chaque entrée dans votre demande. Il peut s’agir de n’importe quelle chaîne unique pour objectWriteTraceId. Par exemple, une demande de création de tickets peut ressembler à ceci : 
///Example request to POST crm/v3/objects/tickets/batch/create
{
  "inputs": [
    {
      "objectWriteTraceId": "549b1c2a9350",
      "properties": {
        "hs_pipeline_stage": "1"
      },
      "objectWriteTraceId": "549b1c2a9351",
      "properties": {
        "missing": "1"
      }
    }
  ]
}
Dans la réponse, les statuts sont regroupés afin que vous puissiez voir quelles créations ont réussi et lesquelles ont échoué. Pour la demande ci-dessus, votre réponse ressemblerait à ceci : 
///Example response
{
  "status": "COMPLETE",
  "results": [
    {
      "id": "1145814089",
      "properties": {
        "createdate": "2024-08-15T17:09:13.648Z",
        "hs_helpdesk_sort_timestamp": "2024-08-15T17:09:13.648Z",
        "hs_last_message_from_visitor": "false",
        "hs_lastmodifieddate": "2024-08-15T17:09:13.648Z",
        "hs_object_id": "1145814089",
        "hs_object_source": "API",
        "hs_object_source_label": "INTERNAL_PROCESSING",
        "hs_pipeline": "0",
        "hs_pipeline_stage": "1",
        "hs_ticket_id": "1145814089"
      },
      "createdAt": "2024-08-15T17:09:13.648Z",
      "updatedAt": "2024-08-15T17:09:13.648Z",
      "archived": false
    }
  ],
  "numErrors": 1,
  "errors": [
    {
      "status": "error",
      "category": "VALIDATION_ERROR",
      "message": "Property values were not valid: [{\"isValid\":false,\"message\":\"Property \\\"missing\\\" does not exist\",\"error\":\"PROPERTY_DOESNT_EXIST\",\"name\":\"missing\",\"localizedErrorMessage\":\"Property \\\"missing\\\" does not exist\",\"portalId\":891936587}]",
      "context": {
        "objectWriteTraceId": ["549b1c2a9351"]
      }
    }
  ],
  "startedAt": "2024-08-15T17:09:13.610Z",
  "completedAt": "2024-08-15T17:09:13.910Z"
}

​
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 :
  • Échec de la connexion : 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 de 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.