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

Este artículo explica cómo solucionar los códigos de error más comunes de los webhooks y el Contenido conectado, y ofrece más explicaciones sobre cómo pueden producirse estos errores en tus solicitudes.

4XX errores

4XX indican que hay un problema con la solicitud enviada al punto final. Estos errores suelen deberse a solicitudes erróneas, como parámetros mal formados, omisión de cabeceras de autenticación o URL incorrectas.

Consulta la tabla siguiente para ver los detalles del código de error y los pasos para solucionarlo:

Código de error	Qué significa	Pasos para resolver
400 Petición errónea	Hay una sintaxis inválida en la petición.	Comprueba que la carga útil de la solicitud no contenga errores de sintaxis. Confirma que todos los campos obligatorios están incluidos y correctamente formateados. Si envías una carga útil JSON, valida la estructura JSON.
401 No autorizado	La solicitud requiere la autenticación del usuario.	Comprueba que se incluyen las credenciales de autenticación correctas (como claves de API o tokens) en los encabezados de solicitud. Confirma que tienes los permisos de usuario para acceder al punto final.
403 Prohibido	El endpoint entiende la petición pero se niega a autorizarla.	Comprueba si la clave de API o el token tienen los permisos necesarios. Confirma que tienes los permisos de usuario para acceder al punto final.
404 No encontrado	El punto final no puede encontrar el recurso solicitado.	Comprueba si la URL del punto final contiene errores tipográficos o rutas incorrectas. Confirma que el recurso al que intentas acceder existe.
405 Método no permitido	El método de solicitud es conocido por el punto final, 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 final admite el método que estás utilizando.
408 Tiempo de espera de la solicitud	El punto final ha agotado el tiempo de procesamiento de la solicitud.	Comprueba el método HTTP (DELETE, GET, POST, PUT) utilizado en la solicitud. Confirma que el punto final admite el método que estás utilizando.
409 Conflicto	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 final admite el método que estás utilizando.
429 Demasiadas peticiones	Se envían demasiadas solicitudes en un tiempo determinado.	Reduce el límite de velocidad en tu campaña o paso en Canvas.

5XX errores

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

Código de error	Qué significa
500 Error interno del servidor	El punto final encontró una condición inesperada que le impidió completar la solicitud.
502 Pasarela incorrecta	El punto final ha recibido una respuesta no válida del servidor ascendente.
503 Servicio no disponible	El punto final no puede gestionar actualmente la solicitud debido a una sobrecarga temporal o a mantenimiento.
504 Tiempo de espera de la puerta de enlace	El punto final no ha recibido una respuesta oportuna del servidor ascendente.
529 Anfitrión sobrecargado	El host del punto final está sobrecargado y no ha podido responder.
598 Anfitrión no sano	Braze simuló la respuesta porque el host del punto final está marcado temporalmente como no saludable. Para saber más, consulta Detección de host no sano.
599 Error de conexión	Braze experimentó un error de tiempo de espera de conexión de red al intentar establecer una conexión con el punto final, lo que significa que el punto final puede ser inestable o estar caído.

Resolver errores 5XX

Aquí tienes consejos para la solución de problemas comunes en 5XX:

• Revisa el mensaje de error para ver los detalles específicos disponibles en el Registro de Actividad de Mensajes. Para los webhooks, ve a la sección Rendimiento en el tiempo de la página de inicio de Braze y selecciona las estadísticas de los webhooks. Desde aquí, puedes encontrar la marca de tiempo que indica cuándo se produjeron los errores.
• Asegúrate de no enviar demasiadas peticiones que sobrecarguen el endpoint. Puedes enviar por lotes o ajustar el límite de velocidad para comprobar si así se reducen los errores.

Detección de host no sano

Los webhooks Braze y el Contenido conectado emplean un mecanismo de detección de host no saludable para detectar cuando el host de destino experimenta una alta tasa de lentitud significativa o una sobrecarga que provoca tiempos de espera, demasiadas solicitudes u otros resultados que impiden que Braze se comunique correctamente con el punto final de destino. Actúa como salvaguarda para reducir la carga innecesaria que pueda estar causando dificultades al host de destino. También sirve para estabilizar la infraestructura de Braze y mantener velocidades rápidas de mensajería.

En general, si el número de fallos supera los 3.000 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 final), Braze detendrá temporalmente las solicitudes al host de destino durante un minuto, simulando en su lugar respuestas con un código de error 598 para indicar la mala salud. Al cabo de un minuto, Braze reanudará las peticiones a toda velocidad si se comprueba que el anfitrión está sano. Si el anfitrión sigue sin estar sano, Braze esperará otro minuto antes de volver a intentarlo.

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

Para los webhooks, Braze reintentará automáticamente las peticiones HTTP que fueron detenidas por el detector de host insalubre. Este reintento automático utiliza una retirada exponencial y sólo lo intentará unas pocas veces antes de fallar. Para más información sobre los errores de webhook, consulta Errores, lógica de reintentos y tiempos de espera.

Para el Contenido conectado, si las solicitudes al anfitrión de destino se detienen por el detector de anfitrión insalubre, Braze continuará mostrando mensajes y seguirá su 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 reintentan cuando son detenidas por el detector de host insalubre, utiliza 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 el soporte de Braze.

Automatización de envíos electrónicos y entradas en el registro de actividad de mensajes

Configuración de envíos electrónicos automatizados

Si experimentas más de 100.000 errores de webhook o de punto final de contenido conectado (incluidos los reintentos) en un espacio de trabajo en un periodo de 24 horas, recibirás un correo electrónico con 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 final
• 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

Los errores del punto final son:

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

Estos correos electrónicos sólo se envían una vez al día a nivel de espacio de trabajo. Si ningún usuario se registra para recibir estos correos electrónicos, se notificará a todos los administradores de la empresa.

Para registrarte para recibir estos correos electrónicos, haz lo siguiente:

1. Vaya a Configuración > Configuración del administrador > Preferencias de notificación.
2. Selecciona Errores de contenido conectado y Errores de webhook en la sección Canvas y campañas.

Entradas del registro de actividad de mensajes

Habrá al menos una entrada en el Registro de actividad de mensajes relacionada con el error que desencadenó el envío por correo electrónico automatizado.