Esta página fue traducida automáticamente y puede contener errores. Para informar de un error de traducción, usa el componente de comentarios situado bajo el sumario, a la derecha de la página.

Solución de problemas de solicitudes de webhook y contenido conectado

Este artículo explica cómo solucionar problemas de códigos de error comunes de webhooks y contenido conectado, y proporciona explicaciones adicionales sobre cómo pueden producirse estos errores en tus solicitudes.

Errores 4XX {#4xx-errors}

Los errores 4XX indican que hay un problema con la solicitud enviada al punto de conexión. Estos errores suelen deberse a solicitudes erróneas, incluyendo parámetros mal formados, encabezados de autenticación faltantes o URL incorrectas. Ten en cuenta que estos errores también se aplican al Generador de informes.

Consulta la siguiente tabla para obtener detalles sobre los códigos de error y los pasos para resolverlos:

Errores 4XX
Código de error	Qué significa	Pasos para resolverlo
400 Bad Request	Hay una sintaxis no válida en la solicitud.	Comprueba la carga útil de la solicitud en busca de errores de sintaxis. Confirma que todos los campos obligatorios están incluidos y correctamente formateados. Si estás enviando una carga útil JSON, valida la estructura JSON. Si estás usando Liquid para incluir etiquetas de personalización en la solicitud de webhook, verifica que Liquid no se resuelva como un valor en blanco ni produzca caracteres que rompan el JSON (como comillas sin escapar). Previsualiza el mensaje para un usuario de prueba para confirmar que la salida renderizada es válida.
401 Unauthorized	La solicitud requiere autenticación del usuario.	Verifica que las credenciales de autenticación correctas (como claves de API o tokens) estén incluidas en los encabezados de la solicitud. Confirma que tienes los permisos de usuario para acceder al punto de conexión.
403 Forbidden	El punto de conexión entiende la solicitud pero se niega a autorizarla.	Comprueba si la clave de API o el token tiene los permisos necesarios. Confirma que tienes los permisos de usuario para acceder al punto de conexión.
404 Not Found	El punto de conexión no puede encontrar el recurso solicitado.	Comprueba la URL del punto de conexión en busca de errores tipográficos o rutas incorrectas. Confirma que el recurso al que intentas acceder existe.
405 Method Not Allowed	El método de solicitud es conocido por el punto de conexión pero no es compatible con el recurso de destino.	Comprueba el método HTTP (DELETE, GET, POST, PUT) utilizado en la solicitud. Confirma que el punto de conexión es compatible con el método que estás utilizando.
408 Request Timeout	El punto de conexión agotó el tiempo de espera al procesar la solicitud.	Comprueba el método HTTP (DELETE, GET, POST, PUT) utilizado en la solicitud. Confirma que el punto de conexión es compatible con el método que estás utilizando.
409 Conflict	La solicitud está incompleta debido a un conflicto con el estado actual del recurso.	Comprueba el método HTTP (DELETE, GET, POST, PUT) utilizado en la solicitud. Confirma que el punto de conexión es compatible con el método que estás utilizando.
429 Too Many Requests	Se han enviado demasiadas solicitudes en un período de tiempo determinado.	Reduce el límite de velocidad en tu campaña o paso en Canvas.

Errores 5XX {#5xx-errors}

Los errores 5XX indican que hay un problema con el punto de conexión. Estos errores suelen deberse a problemas del lado del servidor.

Código de error	Qué significa
500 Internal Server Error	El punto de conexión encontró una condición inesperada que le impidió completar la solicitud.
502 Bad Gateway	El punto de conexión recibió una respuesta no válida del servidor ascendente.
503 Service Unavailable	El punto de conexión no puede gestionar la solicitud actualmente debido a una sobrecarga temporal o mantenimiento.
504 Gateway Timeout	El punto de conexión no recibió una respuesta oportuna del servidor ascendente.
529 Host Overloaded	El host del punto de conexión está sobrecargado y no pudo responder.
598 Host Unhealthy	Braze simuló la respuesta porque el host del punto de conexión está marcado temporalmente como no saludable. Para más información, consulta Detección de host no saludable.
599 Connection Error	Braze experimentó un error de tiempo de espera de conexión de red al intentar establecer una conexión con el punto de conexión, lo que significa que el punto de conexión puede ser inestable o estar caído.

Resolución de errores 5XX

Aquí tienes consejos para solucionar errores 5XX comunes:

Revisa el mensaje de error para obtener detalles específicos disponibles en el Registro de actividad de mensajes. Para webhooks, ve a la sección Performance Over Time en la página de inicio de Braze y selecciona las estadísticas de webhooks. Desde ahí, puedes encontrar la marca de tiempo que indica cuándo ocurrieron los errores.
Asegúrate de que no estás enviando demasiadas solicitudes que sobrecarguen el punto de conexión. Puedes enviar en lotes o ajustar el límite de velocidad para comprobar si esto reduce los errores.

Detección de host no saludable

Los webhooks y el contenido conectado de Braze emplean un mecanismo de detección de host no saludable para detectar cuándo el host de destino experimenta una alta tasa de lentitud significativa o sobrecarga que resulta en tiempos de espera agotados, demasiadas solicitudes u otros resultados que impiden a Braze comunicarse exitosamente con el punto de conexión de destino. Actúa como una protección para reducir la carga innecesaria que puede estar causando problemas al host de destino. También sirve para estabilizar la infraestructura de Braze y mantener velocidades de mensajería rápidas.

Los umbrales de detección difieren entre webhooks y contenido conectado:

Para webhooks: Si el número de fallos supera los 3000 en cualquier ventana de tiempo móvil de un minuto (por combinación única de nombre de host y grupo de aplicaciones—no por ruta de punto de conexión), Braze detiene temporalmente las solicitudes al host de destino durante un minuto.
Para contenido conectado: Si el número de fallos supera los 3000 Y la tasa de error supera el 90 % en cualquier ventana de tiempo móvil de un minuto (por combinación única de nombre de host y grupo de aplicaciones—no por ruta de punto de conexión), Braze detiene temporalmente las solicitudes al host de destino durante un minuto.

Cuando las solicitudes se detienen, Braze simula respuestas con un código de error 598 para indicar el mal estado de salud. Después de un minuto, Braze reanuda las solicitudes a velocidad completa si se determina que el host está saludable. Si el host sigue no saludable, Braze espera otro minuto antes de intentarlo de nuevo.

Los siguientes códigos de error contribuyen al recuento de fallos del detector de host no saludable: 408, 429, 502, 503, 504, 529.

Para webhooks, Braze reintenta automáticamente las solicitudes HTTP que fueron detenidas por el detector de host no saludable. Este reintento automático utiliza retirada exponencial y solo reintenta unas pocas veces antes de fallar. Para más información sobre errores de webhook, consulta Errores, lógica de reintentos y tiempos de espera.

Para contenido conectado, si las solicitudes al host de destino son detenidas por el detector de host no saludable, Braze continúa renderizando mensajes y siguiendo tu lógica Liquid como si hubiera recibido un código de respuesta de error. Si quieres asegurarte de que estas solicitudes de contenido conectado se reintenten cuando son detenidas por el detector de host no saludable, usa la opción :retry. Para más información sobre la opción :retry, consulta Reintentos de contenido conectado.

Si crees que la detección de host no saludable puede estar causando problemas, ponte en contacto con soporte de Braze.

Correos electrónicos automatizados y entradas del registro de actividad de mensajes

Configuración de correos electrónicos automatizados

Si experimentas más de 100 000 errores de punto de conexión de webhook o contenido conectado (incluyendo reintentos) en un espacio de trabajo en un período de 24 horas, Braze te envía un correo electrónico que incluye la siguiente información sobre cómo resolver los errores.

Nombre del espacio de trabajo
Un enlace al Canvas o a la campaña
URL del punto de conexión
Código de error
Hora en que se observó el error por última vez
Enlaces al registro de actividad de mensajes y documentación relacionada

Nota

Puedes configurar el umbral de errores por espacio de trabajo. Para ajustar este umbral, ponte en contacto con soporte de Braze.

Los errores de punto de conexión son:

4XX: 400, 401, 403, 404, 405, 408, 409, 429
5XX: 500, 502, 503, 504, 598, 599

Estos correos electrónicos solo se envían una vez al día a nivel de espacio de trabajo. Si ningún usuario se suscribe a estos correos electrónicos, Braze notifica a todos los administradores de la empresa.

Para suscribirte a recibir estos correos electrónicos, haz lo siguiente:

Ve a Settings > Admin Settings > Notification Preferences.
Selecciona Connected Content Errors y Webhook Errors en la sección Canvas & Campaigns.

Entradas del registro de actividad de mensajes

Si ocurre un fallo, hay al menos una entrada en el Registro de actividad de mensajes relacionada con él. Si la solicitud se reintenta y finalmente tiene éxito, esos detalles están disponibles en Currents y en el uso compartido de datos de Snowflake. Ten en cuenta que incluso si una solicitud finalmente tiene éxito después de un reintento, los errores aún pueden activar el correo electrónico automatizado.

Información adicional sobre fallos en Braze Currents

Para aumentar la transparencia en problemas relacionados con webhooks, Braze transmite eventos detallados de fallos de webhook a Currents y al uso compartido de datos de Snowflake. Estos eventos incluyen solicitudes de webhook fallidas (como respuestas HTTP 4xx o 5xx), proporcionando mayor observabilidad sobre cómo los problemas de webhook pueden afectar la entrega de mensajes. Ten en cuenta que los eventos de fallo incluyen tanto errores terminales como errores que se están reintentando.

Nota

Las solicitudes de contenido conectado no están incluidas en estos eventos de fallo de webhook.

Para más información, consulta el Glosario de eventos de interacción con mensajes.

New Stuff!