Última modificación: 12 de septiembre de 2025
// translate-ignore ‘Descubre cómo manejar los errores comunes de las API al programar usando las API de HubSpot.’; A menos que se especifique de otro modo, la mayoría de los endpoint de HubSpot darán una respuesta de estado satisfactorio 200 OK. Cualquier endpoint que devuelva un código de estado diferente especificará esa respuesta en su documentación. Además, HubSpot tiene varias respuestas de error comunes en muchas API:
  • 207 Multi-Status: es la respuesta cuando hay diferentes estados (por ejemplo, de error y de éxito), lo que ocurre cuando has habilitado el manejo de errores de múltiples estados para los endpoint de creación en bloques de la API de objetos.
  • 401 Unauthorized: es la respuesta cuando la autenticación proporcionada no es válida. Consulta el Resumen sobre autenticación para obtener información sobre las solicitudes de autenticación a la API.
  • 403 Forbidden: es la respuesta cuando la autenticación proporcionada no tiene los permisos adecuados para acceder a la URL específica. Como ejemplo, un token de OAuth que solo tiene acceso al contenido recibirá la respuesta 403 cuando accede a la API de negocios (que requiere acceso a los contactos). Si has confirmado que tu clave de la API o la aplicación privada tiene los permisos necesarios, ponte en contacto con el servicio de asistencia de HubSpot para obtener ayuda.
  • 423 Locked: es la respuesta al intentar sincronizar un gran volumen de datos (por ejemplo, al insertar o actualizar miles de registros de empresa en un periodo de tiempo muy corto). La respuesta durará 2 segundos, por lo que si recibes un error 423, deberás incluir un retraso de al menos 2 segundos entre las solicitudes a la API.
  • 429 Too many requests: es la respuesta cuando tu cuenta o aplicación supera los límites de la tasa de la API. Encuentra sugerencias para trabajar dentro de esos límites en esta página.
  • 477 Migration in Progress: es la respuesta cuando una cuenta de HubSpot actualmente se está migrando entre ubicaciones de alojamiento de datos. HubSpot devolverá un encabezado de respuesta Retry-After que indica cuántos segundos hay que esperar antes de volver a intentar la solicitud (normalmente hasta 24 horas).
  • 502/504 timeouts``502 timeout/504 timeout: son las respuestas cuando se han alcanzado los límites de procesamiento de HubSpot. Estos límites se implementan para evitar que un solo cliente reduzca el rendimiento. Normalmente solo verás estas respuestas de tiempo de espera al realizar una gran cantidad de solicitudes durante un período de tiempo prolongado. Si ves una de estas respuestas, deberías pausar las solicitudes por unos segundos y luego volver a intentarlo.
  • 503 service temporarily unavailable: es la respuesta cuando HubSpot no está disponible temporalmente. Si recibes esta respuesta, debes pausar las solicitudes por unos segundos y luego volver a intentarlo.
  • 521 web server is down: es la respuesta cuando el servidor de HubSpot está inactivo y debería ser un problema temporal. Si recibes esta respuesta, debes pausar las solicitudes por unos segundos y luego volver a intentarlo.
  • 522 connnection timed out: es la respuesta cuando se ha agotado el tiempo de espera de la conexión entre HubSpot y tu aplicación. Si recibes esta respuesta, ponte en contacto con el servicio de asistencia de HubSpot para obtener ayuda.
  • 523 origin is unreachable: es la respuesta cuando HubSpot no puede establecer contacto con tu aplicación. Si recibes esta respuesta, debes pausar las solicitudes por unos segundos y luego volver a intentarlo.
  • 524 timeout: es el código que 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 solicitud de datos de gran tamaño. Si recibes esta respuesta, debes pausar las solicitudes por unos segundos y luego volver a intentarlo.
  • 525/526 SSL issues: es la respuesta cuando el certificado SSL no es válido o el protocolo de intercambio SSL falla. Si recibes esta respuesta, ponte en contacto con el servicio de asistencia de HubSpot para obtener ayuda.
Aparte de estos errores generales, las respuestas de error de HubSpot están diseñadas que las personas las encuentren fáciles de leer. La mayoría de los endpoint no responden con códigos de error, sino que dan una respuesta en formato JSON con información sobre el error.
  • Para las API de objetos de CRM, las respuestas de error incluirán los campos detallados message, code, y context , que proporcionarán información adicional sobre las propiedades requeridas que no se incluyeron en tu solicitud, así como cualquier problema con propiedades mal estructuradas en tu solicitud.
  • Puedes encontrar más información sobre los errores específicos de los endpoint en las páginas de documentación correspondientes a cada uno.
// 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"
}

​
Errores de múltiples estados

En el caso de los endpoint de creación en bloques de las API de objetos’, puedes habilitar respuestas de varios estados que incluyan errores parciales. Esto significa que la respuesta mostrará cuáles registros se crearon y cuáles no. Para hacerlo, incluye un valor único de objectWriteTraceId para cada entrada en tu solicitud. El valor de objectWriteTraceId puede ser cualquier cadena única. Por ejemplo, una solicitud para crear tickets podría verse así: 
///Example request to POST crm/v3/objects/tickets/batch/create
{
  "inputs": [
    {
      "objectWriteTraceId": "549b1c2a9350",
      "properties": {
        "hs_pipeline_stage": "1"
      },
      "objectWriteTraceId": "549b1c2a9351",
      "properties": {
        "missing": "1"
      }
    }
  ]
}
En la respuesta, los estados se agrupan para que puedas ver cuáles acciones de creación tuvieron éxito y cuáles fallaron. Para la solicitud anterior, la respuesta sería la siguiente: 
///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"
}

​
Reintentos

Si tu aplicación o integración tiene un endpoint al que HubSpot hará la llamada, como las suscripciones por webhooks, cualquier error que el endpoint muestre causará que HubSpot vuelva a hacer la solicitud.

​
Webhooks

Si tu servicio tiene problemas para manejar las notificaciones en algún momento, HubSpot volverá a enviar notificaciones fallidas hasta 10 veces. HubSpot reintentará en los siguientes casos:
  • Falló la conexión: HubSpot no puede abrir una conexión HTTP a la URL de la webhook proporcionada.
  • Tiempo de espera: tu servicio tarda más de 5 segundos en enviar una respuesta a un bloque 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 enviar la solicitud 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 volverán a enviar la solicitud automáticamente después de recibir una respuesta 429 y respetarán el encabezado Retry-After si está presente. Ten en cuenta que el valor de Retry-After está en milisegundos. Las notificaciones se volverán a enviar hasta 10 veces. Los reintentos se distribuirán durante las siguientes 24 horas, con distintos tiempos de retraso entre las solicitudes. Las notificaciones se enviarán de manera aleatoria, para evitar que se vuelva a enviar un gran número de errores concurrentes al mismo tiempo.

​
Acciones de workflow con código personalizado

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