Handling errors

A menos que se especifique lo contrario, la mayoría de los puntos de terminación de HubSpot devolverá una respuesta satisfactoria 200 OK. Cualquier parámetro que regrese a un código de estado diferente especificará la respuesta devuelta en su documentación.

Además, HubSpot tiene varias respuestas de error comunes a múltiples API:

  • 401 Unauthorized: se devuelve cuando la autentificación proporcionada no es válida. Consulta nuestro Resumen de autentificación para obtener información sobre las solicitudes de autentificación de API.
  • 403 Forbidden: se devuelve cuando la autentificación proporcionada no tiene los permisos adecuados para acceder a la URL específica. Como ejemplo, un token de OAuth que solo tiene acceso de contenido recibirá 403 cuando accede a la API de Negocios (que requiere acceso a contactos). Si has confirmado que tu clave API o aplicación privada tiene los permisos necesarios, ponte en contacto con asistencia técnica de HubSpot para obtener ayuda. 
  • 429 Too many requests: se devuelve cuando tu cuenta o aplicación supera los límites de la tasa de API. Encuentra sugerencias para trabajar dentro de esos límites aquí.
  • 477 Migración en curso: devuelto cuando una cuenta de HubSpot se está migrando actualmente entre ubicaciones de alojamiento de datos. HubSpot devolverá un encabezado de Reintentar después de la respuesta que indica cuántos segundos hay que esperar antes de volver a intentar la solicitud (normalmente hasta 24 horas). 
  • 502/504 timeouts: se devuelve cuando se han cumplido los límites de procesamiento de HubSpot. Estos límites se implementan para evitar que un solo cliente cause un rendimiento degradado. Normalmente solo verás estas respuestas de tiempo de espera al realizar una gran cantidad de solicitudes durante un período de tiempo sostenido. Si obtienes una de estas respuestas, deberías pausar tus solicitudes por unos segundos y luego volver a intentarlo.
  • 503 service temporarily unavailable: se devuelve cuando HubSpot no está disponible temporalmente. Si obtienes esta respuesta, deberías pausar tus solicitudes por unos segundos y luego volver a intentarlo.
  • 521 web server is down: se devuelve cuando el servidor de HubSpot está inactivo, esto debería ser un problema temporal. Si obtienes esta respuesta, deberías pausar tus solicitudes por unos segundos y luego volver a intentarlo.
  • 522 connnection timed out: se devuelve cuando se ha agotado el tiempo de espera de la conexión entre HubSpot y tu aplicación. Si has recibido esta respuesta, ponte en contacto con asistencia técnica de HubSpot para obtener ayuda. 
  • 523 origin is unreachable: se devuelve cuando HubSpot no puede ponerse en contacto con tu aplicación. Si obtienes esta respuesta, deberías pausar tus solicitudes por unos segundos y luego volver a intentarlo. 
  • 524 timeout: se devuelve cuando no se recibe una respuesta dentro de 100 segundos. Esto puede ocurrir cuando el servidor de HubSpot está sobrecargado, como con una consulta de datos grande. Si obtienes esta respuesta, deberías pausar tus solicitudes por unos segundos y luego volver a intentarlo.
  • 525/526 SSL issues: se devuelve cuando el certificado SSL no es válido o el apretón de manos SSL falla. Si has recibido esta respuesta, ponte en contacto con asistencia técnica de HubSpot para obtener ayuda. 

Además de estos errores generales, las respuestas de error de HubSpot están diseñadas para ser legibles por personas. La mayoría de los puntos finales no devuelven códigos de error, pero devuelven una respuesta con formato JSON con detalles sobre el error. Puedes encontrar más información sobre los errores específicos de puntos finales en las páginas de documentación correspondientes al punto final.

Nota: los campos de la respuesta del ejemplo a continuación deben ser tratados como opcionales en cualquier error al analizar. Los campos específicos incluidos pueden variar entre diferentes API, por lo tanto, cualquier análisis de errores debería permitir que falten campos específicos en la respuesta.

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

Reintentos

Si tu aplicación o integración proporciona un punto de terminación que HubSpot llamará, como suscripciones de webhook, cualquier error que tu punto de terminación lance hará que HubSpot vuelva a intentar la solicitud. 

Webhooks

Si tu servicio tiene problemas para manejar las notificaciones en cualquier momento, HubSpot intentará volver a enviar notificaciones fallidas hasta 10 Veces.

HubSpot lo intentará nuevamente en los casos siguientes:

  • Falló la conexión: HubSpot no puede abrir una conexión http a la URL de webhook proporcionada
  • Tiempo de espera: tu servicio demora más de 5 segundos en enviar una respuesta a un lote de notificaciones
  • Códigos de error: tu servicio responde con cualquier código de estado HTTP (4xx o 5xx)
Los workflows  no volverán a intentarlo después de recibir los códigos de estado de respuesta de la serie 4XX. Una excepción a esta regla son los errores de límite de frecuencia 429; los workflows reintentarán automáticamente después de recibir una respuesta 429 y respetarán el encabezado Reintentar después  si está presente. Ten en cuenta que el valor de Reintentar después está en milisegundos.

Las notificaciones se volverán a intentar hasta 10 Veces. Estos reintentos se distribuirán durante las próximas 24 horas, con distintos retrasos entre las solicitudes. Las notificaciones individuales serán enviadas de manera aleatoria, para evitar que un gran número de errores concurrentes se vuelva a intentar en el mismo momento.

Acciones de workflow de código personalizado

Si estás creando una acción de código personalizado en un workflow y una llamada a la API en tu acción falla debido a un error de límite de velocidad o un error 429 o 5XX de axios o @hubspot/api-client, HubSpot volverá a intentar ejecutar tu acción durante un máximo de tres días, comenzando un minuto después del error. Los fallos posteriores se volverán a intentar a intervalos cada vez mayores, con un intervalo máximo de ocho horas entre intentos.

¿Te resultó útil este artículo?
Con este formulario puedes enviar tu opinión sobre nuestros documentos para desarrolladores. Si tienes comentarios sobre el producto de HubSpot, puedes enviarlos al Foro de ideas.