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

Usa esta página para solucionar problemas de códigos de error comunes de webhooks y contenido conectado. Para la configuración, consulta Crear un webhook y Realizar una llamada a la API. Para inspeccionar una solicitud de contenido conectado en la vista previa, consulta Depurador de contenido conectado.

Empieza aquí: Identifica tu síntoma

Identifica tu síntoma en la tabla para navegar a la sección relevante.

Síntoma	Ir a
Error de cliente `4XX` en el registro de actividad de mensajes	Errores 4XX
Error de servidor `5XX` o tiempo de espera agotado	Errores 5XX
`598 Host Unhealthy` o solicitudes detenidas brevemente	Detección de host no saludable
El contenido conectado aparece en blanco en la vista previa o el envío	El contenido conectado no devuelve cuerpo de respuesta
Necesitas inspeccionar una solicitud de contenido conectado en la vista previa	Depurador de contenido conectado
Correo electrónico automatizado de Braze	Correos electrónicos automatizados y entradas del registro de actividad de mensajes
Necesitas eventos de fallo de webhook en Currents	Información adicional sobre fallos en Braze Currents

Ruta de investigación estándar

Utiliza este flujo de trabajo cuando una solicitud de webhook o contenido conectado falle o se represente de forma incorrecta. Empieza en el paso 1.

Abre el registro de actividad de mensajes y anota el código de error, la marca de tiempo y la URL del endpoint.
Para errores 4XX, verifica la sintaxis de la solicitud, los encabezados de autenticación, la ruta de la URL y el método HTTP con la documentación del endpoint.
Para errores 5XX, comprueba el estado del endpoint, los límites de velocidad y si Braze marcó el host como no saludable.
Para contenido conectado, previsualiza el mensaje para un usuario de prueba. Usa el depurador de contenido conectado para inspeccionar la solicitud y la respuesta, y confirma que Liquid no se resuelve con valores en blanco o que rompan el JSON.
Si la detección de hosts no saludables puede estar implicada, revisa Detección de hosts no saludables antes de ponerte en contacto con soporte de Braze.

Errores 4XX {#4xx-errors}

Los errores 4XX indican que hay un problema con la solicitud enviada al endpoint. Estos errores suelen deberse a solicitudes erróneas, incluidos parámetros con formato incorrecto, 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:

Código de error	Qué significa	Pasos para resolverlo
400 Bad Request	La sintaxis de la solicitud no es válida.	Verifica la carga útil de la solicitud en busca de errores de sintaxis. Confirma que todos los campos obligatorios están incluidos y con el formato correcto. Si estás enviando una carga útil JSON, valida la estructura del JSON. Si estás usando Liquid para incluir etiquetas de personalización en la solicitud de webhook, verifica que el Liquid no se resuelva con un valor en blanco ni produzca caracteres que rompan el JSON (como comillas sin escapar). Previsualiza el mensaje para un usuario de prueba y confirma que la salida renderizada es válida.
401 Unauthorized	La solicitud requiere autenticación de 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 endpoint.
403 Forbidden	El endpoint entiende la solicitud, pero se niega a autorizarla.	Verifica si la clave de API o el token tiene los permisos necesarios. Confirma que tienes los permisos de usuario para acceder al endpoint. Si las solicitudes devuelven consistentemente `403` y la autenticación parece correcta, es posible que tu servidor, puerta de enlace de API o WAF esté bloqueando las direcciones IP de salida de Braze. Añade las IP de tu clúster de Braze a la lista de permitidos. Para webhooks, consulta Lista de IP permitidas. Para contenido conectado, consulta Lista de IP permitidas de contenido conectado.
404 Not Found	El endpoint no puede encontrar el recurso solicitado.	Verifica la URL del endpoint en busca de errores tipográficos o rutas incorrectas. Confirma que el recurso al que intentas acceder existe.
405 Method Not Allowed	El endpoint conoce el método de solicitud, pero el recurso de destino no lo admite.	Verifica el método HTTP (DELETE, GET, POST, PUT) utilizado en la solicitud. Confirma que el endpoint admite el método que estás usando.
408 Request Timeout	El endpoint agotó el tiempo de espera al procesar la solicitud.	Verifica el método HTTP (DELETE, GET, POST, PUT) utilizado en la solicitud. Confirma que el endpoint admite el método que estás usando.
409 Conflict	La solicitud está incompleta debido a un conflicto con el estado actual del recurso.	Verifica el método HTTP (DELETE, GET, POST, PUT) utilizado en la solicitud. Confirma que el endpoint admite el método que estás usando.
429 Too Many Requests	Se han enviado demasiadas solicitudes en un período de tiempo determinado.	Reduce el límite de velocidad en tu Campaign o paso en Canvas.

Errores 5XX {#5xx-errors}

Los errores 5XX indican que hay un problema con el endpoint. Estos errores suelen deberse a problemas del lado del servidor.

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

Resolución de errores 5XX

Aquí tienes algunos consejos para la solución de problemas de los errores 5XX más comunes:

Revisa el mensaje de error en busca de 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 endpoint. 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 endpoint 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 endpoint), 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 endpoint), 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.

El contenido conectado no devuelve cuerpo de respuesta

Síntoma: Una llamada de contenido conectado se renderiza en blanco en la vista previa o el envío de tu mensaje.

Si una llamada de contenido conectado se renderiza en blanco en la vista previa o el envío de tu mensaje, usa el Depurador de contenido conectado para inspeccionar la solicitud y la respuesta, y luego comprueba lo siguiente:

Espacios de no separación en la URL: Braze elimina los espacios de no separación (  o Unicode U+00A0) de las URL de contenido conectado antes de realizar la solicitud. Si tu URL fue copiada de un documento o campo del panel que insertó espacios de no separación entre caracteres, la solicitud puede fallar o no devolver un cuerpo utilizable. Vuelve a escribir la URL en texto plano o elimina los espacios ocultos, y luego previsualiza de nuevo.
Respuestas de redirección (3xx): El contenido conectado no sigue redirecciones. Solo las respuestas 2xx se tratan como exitosas, por lo que un 301 o 302 puede renderizarse en blanco incluso cuando la misma URL funciona en Postman. Usa la URL de destino final o configura el endpoint para que devuelva una respuesta 2xx (normalmente 200) en la URL que Braze llama. Consulta ¿Por qué falla el contenido conectado cuando mi endpoint devuelve una redirección?.
Errores HTTP y cuerpos vacíos: Para códigos de estado fuera del rango 2xx o hosts bloqueados, el contenido conectado puede renderizar una cadena vacía. Consulta Realizar una llamada a la API y revisa los fallos en el Registro de actividad de mensajes.

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 endpoint 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 endpoint
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 endpoint 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 Configuración > Configuración de administrador > Preferencias de notificación.
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 desencadenar 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!