Handling errors

A menos que especificado de outra forma, a maioria dos endpoints do HubSpot retornará uma resposta 200 OK após o sucesso. Todos os endpoints que retornaram um código de status diferente especificarão a resposta retornada na sua documentação.

Além disso, o HubSpot tem várias respostas de erros comuns a várias APIs:

  • 401 Não autorizado - retornado quando a autenticação fornecida é inválida. Veja nossa Visão geral de autenticação para obter detalhes sobre as solicitações de API autenticadas.
  • 403 Proibido: retornado quando a autenticação fornecida não tem as permissões adequadas para acessar a URL específica. Como exemplo, um token de OAuth que só tem acesso de conteúdo receberá um 403 ao acessar a API Negócios (que exige acesso de contatos). Se você confirmou que sua chave de API ou aplicativo privado tem as permissões necessárias, entre em contato com o suporte da HubSpot para obter assistência. 
  • 429 Solicitações demais: retornando quando a conta ou o aplicativo está acima de seus limites de taxa de API. Encontre sugestões em trabalhar dentro desses limites aqui.
  • 477 Migração em andamento: retornado quando uma conta da HubSpot está sendo migrada entre locais de hospedagem de dados. O HubSpot retornará o cabeçalho de resposta Retry-After, que indica o número de segundos após os quais a solicitação será repetida (normalmente até 24 horas). 
  • 502/504 tempo limite: retornado quando os limites de processamento da HubSpot foram atendidos. Esses limites estão em vigor para impedir que um único cliente cause redução de desempenho. Essas respostas de tempo limite ocorrem ao fazer um grande número de solicitações ao longo de um período prolongado. Se você receber uma dessas respostas, você deve pausar suas solicitações por alguns segundos e tentar novamente.
  • 503 serviço temporariamente indisponível: retornado quando o HubSpot está temporariamente indisponível. Se você receber essa resposta, deve pausar suas solicitações por alguns segundos e tentar novamente.
  • 521 servidor da Web está inativo: retornado quando o servidor do HubSpot está inativo. Isso deve ser um problema temporário. Se você receber essa resposta, deve pausar suas solicitações por alguns segundos e tentar novamente.
  • 522 tempo limite de conexão: retornado quando a conexão entre o HubSpot e o aplicativo atingiu o tempo limite. Se você recebeu essa resposta, entre em contato com o suporte da HubSpot para obter assistência. 
  • 523 origem está inacessível: retornada quando o HubSpot não consegue entrar em contato com seu aplicativo. Se você receber essa resposta, deve pausar suas solicitações por alguns segundos e tentar novamente. 
  • 524 tempo limite: retornado quando uma resposta não é recebida dentro de 100 segundos. Isso pode ocorrer quando o servidor do HubSpot está sobrecarregado, como com uma consulta de dados grande. Se você receber essa resposta, deve pausar suas solicitações por alguns segundos e tentar novamente.
  • 525/526 problemas SSL: retornado quando o certificado SSL é inválido ou o aperto de mão SSL falha. Se você recebeu essa resposta, entre em contato com o suporte da HubSpot para obter assistência. 

Além desses erros gerais, as respostas de erro do HubSpot são projetadas para compreensíveis aos usuários. A maioria dos endpoints não retorna códigos de erro, mas uma resposta de JSON formatada com detalhes sobre o erro. Mais detalhes para erros específicos de endpoint podem ser encontrados nas páginas de documentação para o final.

Observação: os campos no exemplo de resposta abaixo devem ser tratados como opcionais em qualquer análise de erro. Os campos específicos incluídos podem variar entre APIs diferentes, portanto qualquer análise de erro deve possibilitar que os campos específicos estejam ausentes da resposta.

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

Tentativas

Se o aplicativo ou a integração fornecer um endpoint que a HubSpot chamará, como assinaturas de webhook, todos os erros que o endpoint lançar farão com que a HubSpot repita a solicitação. 

Webhooks

Se, em algum momento, o serviço enfrentar problemas ao lidar com notificações, o HubSpot fará 10 tentativas de reenviar as notificações com falha.

O HubSpot tentará novamente nos seguintes casos:

  • Falha na conexão: se o HubSpot não conseguir estabelecer uma conexão http com a URL do webhook fornecida.
  • Tempo limite: se o serviço demorar mais de 5 segundos para enviar uma resposta a um lote de notificações
  • Códigos de erro: se o serviço responder com qualquer código de status HTTP (4xx ou 5xx)
Os fluxos de trabalho não serão repetidos depois de receber códigos de status de resposta da série 4XX. Uma exceção a esta regra são os erros de limite de taxa 429; os fluxos de trabalho serão repetidos automaticamente depois de receber uma resposta 429 e respeitarão o cabeçalho Retry-After, se estiver presente. Observe que o valor Retry-After está em milissegundos.

As notificações serão repetidas até 10 vezes. Essas tentativas serão divulgadas nas próximas 24 horas, com atrasos variáveis entre solicitações. Será aplicada uma randomização às notificações individuais para evitar que um grande número de falhas simultâneas sejam repetidas exatamente mesmo horário.

Ações de fluxo de trabalho de código personalizado

Se você estiver criando uma ação de código personalizado em um fluxo de trabalho e a chamada de API em sua ação falhar devido a um erro de limitação de taxa ou um erro 429 ou 5XX do axios ou do @hubspot/api-client, a HubSpot tentará novamente executar sua ação por até três dias, começando um minuto após a falha. As falhas subsequentes serão tentadas novamente em intervalos crescentes, com uma lacuna máxima de oito horas entre as tentativas.

Este artigo foi útil?
Este formulário deve ser usado apenas para fazer comentários sobre esses artigos. Saiba como obter ajuda para usar a HubSpot..