Límites de velocidad
La infraestructura de la API de Braze está diseñada para gestionar grandes volúmenes de datos de toda nuestra base de clientes. Para ello, imponemos límites de velocidad de API por espacio de trabajo.
Un límite de velocidad es el número de solicitudes que puede recibir la API en un periodo de tiempo determinado. Muchos incidentes de denegación de servicio basados en la carga en grandes sistemas son involuntarios —causados por errores en el software o las configuraciones—, no ataques maliciosos. Los límites de velocidad comprueban que esos errores no priven a nuestros clientes de los recursos de la API de Braze. Si se envían demasiadas solicitudes en un periodo de tiempo determinado, es posible que veas respuestas de error con un código de estado 429, que indica que se ha alcanzado el límite de velocidad.
Los límites de velocidad de la API están sujetos a cambios en función del uso adecuado de nuestro sistema. Animamos a que se establezcan límites razonables al realizar una llamada a la API para evitar daños o usos indebidos.
Límites de velocidad por tipo de solicitud
Consulta a continuación los límites de velocidad predeterminados de la API para los distintos tipos de solicitud. Estos límites predeterminados se pueden aumentar si lo solicitas. Ponte en contacto con tu administrador del éxito del cliente para obtener más información.
Solicitudes con distintos límites de velocidad
| Tipo de solicitud | Límite de velocidad predeterminado de la API |
|---|---|
/users/track |
Solicitudes: Los límites de velocidad varían en función de tu contrato. Para los clientes con puntos de datos en su tarifa, Braze aplica un límite de ráfaga de 3000 solicitudes cada tres segundos. Para el resto de los clientes, los límites se configuran según las condiciones de su contrato. Ponte en contacto con el soporte de Braze o con tu administrador del éxito del cliente si tienes preguntas sobre tus límites. Agrupación por lotes: Hasta 75 objetos en total combinados entre attributes, events y purchases por solicitud de API. Los clientes con límites de velocidad heredados pueden incluir hasta 75 objetos por matriz de forma independiente. Para más información, consulta Agrupación por lotes de solicitudes de seguimiento de usuarios.Límites para usuarios activos mensuales CY 24-25, MAU universales, MAU web y MAU móviles: Consulta Límites de usuarios activos mensuales CY 24-25. |
/users/track/status |
1500 solicitudes por minuto. |
/users/export/ids |
Si te incorporaste el 22 de agosto de 2024 o después: 250 solicitudes por minuto. Si te incorporaste antes del 22 de agosto de 2024: 2500 solicitudes por minuto. |
/users/delete/users/alias/new/users/alias/update/users/identify/users/merge |
20 000 solicitudes por minuto, compartidas entre los endpoints. |
/users/external_id/rename |
1000 solicitudes por minuto. |
/users/external_id/remove |
1000 solicitudes por minuto. |
/events/list |
1000 solicitudes por hora, compartidas con el endpoint /purchases/product_list. |
/purchases/product_list |
1000 solicitudes por hora, compartidas con el endpoint /events/list. |
/campaigns/data_series |
50 000 solicitudes por minuto. |
/messages/send/campaigns/trigger/send/canvas/trigger/send/campaigns/trigger/schedule/create/canvas/trigger/schedule/create |
Para las llamadas de difusión (cuando se dirigen de forma amplia a Segments, filtros o una audiencia conectada), 250 solicitudes por minuto entre todas las audiencias y 10 solicitudes por minuto por audiencia única (el límite que se alcance primero). En los demás casos, cuando te diriges a destinatarios individuales, la solicitud se incluye en el límite de velocidad compartido de 250 000 solicitudes por hora. |
/sends/id/create |
100 solicitudes por día. |
/subscription/status/set |
5000 solicitudes por minuto. |
/preference_center/v1/{preferenceCenterExternalId}/url/{userId}/preference_center/v1/list/preference_center/v1/{preferenceCenterExternalId} |
1000 solicitudes por minuto. |
/preference_center/v1/preference_center/v1/{preferenceCenterExternalId} |
10 solicitudes por minuto. |
/catalogs/{catalog_name}/catalogs/catalogs |
50 solicitudes por minuto, compartidas entre los endpoints. |
/catalogs/{catalog_name}/items/catalogs/{catalog_name}/items/catalogs/{catalog_name}/items |
16 000 solicitudes por minuto, compartidas entre los endpoints. |
/catalogs/{catalog_name}/items/{item_id}/catalogs/{catalog_name}/items/{item_id}/catalogs/{catalog_name}/items/catalogs/{catalog_name}/items/{item_id}/catalogs/{catalog_name}/items/{item_id} |
50 solicitudes por minuto, compartidas entre los endpoints. |
/catalogs/{catalog_name}/fields/{field_name}/catalogs/{catalog_name}/fields/catalogs/{catalog_name}/selections/{selection_name}/catalogs/{catalog_name}/selections |
50 solicitudes por minuto, compartidas entre los endpoints. |
/scim/v2/Users/{id}/scim/v2/Users?filter={[email protected]}/scim/v2/Users/{id}/scim/v2/Users/{id}}/scim/v2/Users/ |
20 000 solicitudes por día, por empresa, compartidas entre los endpoints. |
/cdi/integrations |
50 solicitudes por minuto. |
/cdi/integrations/{integration_id}/sync |
20 solicitudes por minuto. |
/cdi/integrations/{integration_id}/job_sync_status |
100 solicitudes por minuto. |
/media_library/create |
100 solicitudes por hora. |
/media_library/replace_file |
100 solicitudes por hora. |
Solicitudes con límites de velocidad compartidos
Las siguientes solicitudes tienen un límite de velocidad de 250 000 solicitudes por hora, compartido entre ellas.
/app_group/sdk_authentication/create/app_group/sdk_authentication/keys/app_group/sdk_authentication/delete/app_group/sdk_authentication/primary/campaigns/details/campaigns/list/campaigns/trigger/send(solo para llamadas que no son de difusión—las que especificanexternal_user_idsoaliases)/campaigns/trigger/schedule/create(solo para llamadas que no son de difusión)/campaigns/trigger/schedule/delete/campaigns/trigger/schedule/update/canvas/data_series/canvas/data_summary/canvas/details/canvas/list/canvas/trigger/send(solo para llamadas que no son de difusión)/canvas/trigger/schedule/create(solo para llamadas que no son de difusión)/canvas/trigger/schedule/delete/canvas/trigger/schedule/update/content_blocks/create/content_blocks/info/content_blocks/list/content_blocks/update/email/blocklist/email/blacklist/email/bounce/remove/email/hard_bounces/email/spam/remove/email/status/email/unsubscribes/events/data_series/kpi/dau/data_series/kpi/mau/data_series/kpi/new_users/data_series/kpi/uninstalls/data_series/messages/live_activity/start/messages/live_activity/update/messages/send(solo para llamadas que no son de difusión)/messages/schedule/create/messages/schedule/delete/messages/schedule/update/messages/scheduled_broadcasts/segments/data_series/segments/details/segments/list/sends/data_series/sessions/data_series/sms/invalid_phone_numbers/sms/invalid_phone_numbers/remove/subscription/status/get/subscription/user/status/templates/email/create/templates/email/info/templates/email/list/templates/email/update/users/export/global_control_group/users/export/segment
¿Qué se considera la misma audiencia única?
Esto se aplica a los siguientes endpoints: /messages/send, /campaigns/trigger/send, /canvas/trigger/send, /campaigns/trigger/schedule/create y /canvas/trigger/schedule/create.
Para estos endpoints, se considera que las solicitudes de difusión se dirigen a la misma audiencia única cuando coinciden todos los elementos siguientes:
- La campaña o el Canvas que se desencadena (el
campaign_ido elcanvas_idde tu solicitud de API, si se especifica) - La audiencia a la que te diriges (los Segments o filtros o, para las campañas API, el
segment_idde tu solicitud de API) - Los filtros de audiencia conectada (el objeto
audiencede tu solicitud de API, si se especifica)
Cada combinación única de estos atributos cuenta como una audiencia distinta, por lo que el límite de velocidad adicional para cada audiencia única se aplica a cada combinación de forma independiente.
Solicitudes de API por lotes
Las API de Braze están diseñadas para admitir el procesamiento por lotes. Con los lotes, Braze puede recibir la mayor cantidad de datos posible en una sola llamada a la API, así no necesitas hacer muchas llamadas. Para Braze es más eficiente procesar datos por lotes que procesarlos llamada a llamada. Por ejemplo, gestionar 1000 llamadas a la API por lotes requiere menos recursos que gestionar 75 000 llamadas individuales. El procesamiento por lotes es muy importante para cualquier aplicación que pueda necesitar más de 75 000 llamadas por hora.
Los aumentos del límite de velocidad de la REST API se evalúan según la necesidad de los clientes que utilizan las capacidades de procesamiento por lotes de la API.
Solicitudes por lotes para el endpoint Crear y actualizar usuarios
Cada solicitud a /users/track puede contener hasta 75 objetos en total, combinando attributes, events y purchases. Cada objeto puede actualizar a un usuario. Un mismo perfil de usuario puede actualizarse con varios objetos.
Legacy rate limits
Para los clientes con límites de velocidad heredados, cada matriz (attributes, events y purchases) puede contener hasta 75 objetos de forma independiente, con un máximo combinado de hasta 225 objetos por solicitud.
Para más información sobre los límites de velocidad de /users/track, consulta POST: Crear y actualizar usuarios.
Las solicitudes realizadas a este endpoint suelen empezar a procesarse en este orden:
- Atributos
- Eventos
- Compras
Solicitudes por lotes a los endpoints de mensajería
Una sola solicitud a los endpoints de mensajería puede llegar a cualquiera de los siguientes:
- Hasta 50
external_idsespecíficos, cada uno con parámetros de mensaje individuales - Un Segment de cualquier tamaño creado en el panel de Braze, especificado por su
segment_id - Usuarios que coincidan con filtros de audiencia adicionales de cualquier tamaño, definidos en la solicitud como un objeto de audiencia conectada
Ejemplo de solicitud por lotes
El siguiente ejemplo utiliza external_id para hacer una sola llamada a la API para correo electrónico y SMS.
curl --location --request POST 'https://rest.iad-01.braze.com/v2/subscription/status/set' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-REST-API-KEY' \
--data-raw '{
"subscription_groups":[
{
"subscription_group_id":"subscription_group_identifier",
"subscription_state":"subscribed",
"external_ids":["example-user","[email protected]"]
},
{
"subscription_group_id":"subscription_group_identifier",
"subscription_state":"subscribed",
"external_ids":["example-user","[email protected]"]
}
]
}
Supervisión de tus límites de velocidad
Cada solicitud a la API enviada a Braze que esté sujeta al límite de velocidad estándar de la REST API devuelve la siguiente información en los encabezados de la respuesta:
| Nombre del encabezado | Descripción |
|---|---|
X-RateLimit-Limit |
El número máximo de solicitudes que puedes hacer en un intervalo especificado (tu límite de velocidad). |
X-RateLimit-Remaining |
El número de solicitudes restantes en la ventana actual del límite de velocidad. |
X-RateLimit-Reset |
El momento en que se restablece la ventana actual del límite de velocidad, en segundos de época UTC. |
Los endpoints que omiten el límite de velocidad estándar de la REST API, como los endpoints de correo transaccional, no cuentan para tu límite de velocidad general de la API externa y no devuelven estos encabezados.
Esta información se incluye intencionadamente en el encabezado de la respuesta a la solicitud a la API y no en el panel de Braze. Esto permite que tu sistema reaccione mejor en tiempo real mientras interactúas con nuestra API. Por ejemplo, si el valor de X-RateLimit-Remaining cae por debajo de cierto umbral, quizá quieras ralentizar tus solicitudes. O, si llega a cero, quizá quieras pausar las solicitudes hasta que transcurra el tiempo especificado en X-RateLimit-Reset.
Solución de problemas de respuestas 429 Too Many Requests
Si un endpoint devuelve una respuesta HTTP 429 Too Many Requests porque tu integración superó un límite de velocidad, utiliza los encabezados de la respuesta para determinar cuándo volver a intentarlo:
- Pausa las solicitudes. Si la respuesta incluye
X-RateLimit-Retry-After, espera el número de segundos especificado. De lo contrario, espera hasta la marca de tiempo de época UTC indicada enX-RateLimit-Reset. - Reanuda las solicitudes a una tasa más baja. Envía menos solicitudes en cada ventana del límite de velocidad para reducir la probabilidad de otra respuesta
429. - Cuando sea posible, combina varias actualizaciones en cada solicitud. Para
/users/track, sigue el límite de objetos por solicitud de tu cuenta. - Utiliza el panel de uso de la API para identificar picos de solicitudes y tendencias de respuestas
429.
Para conocer los valores predeterminados de cada endpoint, consulta Límites de velocidad por tipo de solicitud.
Los encabezados HTTP se devolverán en minúsculas. Este comportamiento se ajusta al protocolo HTTP/2, que exige que todos los nombres de los campos de encabezado estén en minúsculas. Esto difiere de HTTP/1.X, en el que los nombres de los encabezados no distinguían entre mayúsculas y minúsculas, pero solían escribirse con distintas combinaciones de mayúsculas.
Si tienes preguntas sobre los límites de la API, ponte en contacto con tu administrador de éxito del cliente o abre un ticket de soporte.
Puedes utilizar el panel de uso de la API para ver y comparar el tráfico entrante con tus límites de velocidad.
Retraso óptimo entre endpoints
Te recomendamos dejar un retraso de 5 minutos entre llamadas consecutivas a endpoints para minimizar los errores.
Comprender el retraso óptimo entre endpoints es fundamental al hacer llamadas consecutivas a la API de Braze. Surgen problemas cuando los endpoints dependen del procesamiento correcto de otros endpoints y, si se llaman demasiado pronto, pueden generar errores. Por ejemplo, si asignas un alias a los usuarios a través de nuestro endpoint /user/alias/new y luego usas ese alias para enviar un evento personalizado a través de nuestro endpoint /users/track, ¿cuánto tiempo deberías esperar?
En condiciones normales, el tiempo necesario para que se produzca la consistencia eventual de nuestros datos es de 10-100 ms (1/10 de segundo). Sin embargo, puede haber casos en los que esa consistencia tarde más en producirse, por lo que te recomendamos dejar un retraso de 5 minutos entre llamadas sucesivas para minimizar la probabilidad de error.
Límites de tamaño de la carga útil
Las solicitudes a la API de Braze están sujetas a límites de tamaño de la carga útil, independientes de los límites de velocidad. La mayoría de los endpoints aceptan cuerpos de solicitud de hasta 4 MB. Cuando una solicitud supera el límite aplicable, Braze puede rechazarla con HTTP 413 Request Entity Too Large o HTTP 400 Bad Request, según el endpoint.
El endpoint /users/track/bulk tiene un límite de carga útil de 2 MB y devuelve HTTP 400 cuando el cuerpo de la solicitud supera ese límite. Para conocer los límites específicos de cada endpoint y la gestión de errores, consulta Endpoints de datos de usuario.
Restablecimiento del límite de velocidad
Los límites de velocidad se restablecen en cada hora en punto, no en una ventana móvil. Por ejemplo, si el límite es de 250 000 solicitudes por hora, podrías hacer 50 000 solicitudes entre las 22:00 y las 22:59 y otras 250 000 solicitudes entre las 23:00 y las 23:59, porque el contador se restablece al comienzo de cada hora.