Limites de débit
L’infrastructure API de Braze est conçue pour gérer d’importants volumes de données pour l’ensemble de notre clientèle. C’est pourquoi nous appliquons des limites de débit de l’API par espace de travail.
Une limite de débit correspond au nombre de requêtes que l’API peut recevoir sur une période donnée. Dans les grands systèmes, de nombreux incidents de déni de service liés à la charge sont involontaires : ils sont causés par des erreurs logicielles ou de configuration, et non par des attaques malveillantes. Les limites de débit permettent de s’assurer que ces erreurs ne privent pas nos clients des ressources de l’API de Braze. Si trop de requêtes sont envoyées sur une période donnée, vous pouvez recevoir des réponses d’erreur avec le code d’état 429, qui indique que la limite de débit a été atteinte.
Les limites de débit de l’API sont susceptibles d’évoluer en fonction de l’utilisation appropriée de notre système. Nous vous recommandons de définir des limites raisonnables lors de vos appels API afin d’éviter tout dommage ou toute utilisation abusive.
Limites de débit par type de requête
Voici les limites de débit par défaut de l’API pour les différents types de requêtes. Ces limites par défaut peuvent être augmentées sur demande. Pour en savoir plus, contactez votre gestionnaire de la satisfaction client.
Requêtes avec des limites de débit différentes
| Type de requête | Limite de débit par défaut de l’API |
|---|---|
/users/track |
Requêtes : Les limites de débit varient selon votre contrat. Pour les clients dont la tarification inclut des points de données, Braze applique une limite de rafale de 3 000 requêtes toutes les trois secondes. Pour tous les autres clients, les limites sont configurées selon les termes de votre contrat. Pour toute question sur vos limites, contactez le support de Braze ou votre gestionnaire de la satisfaction client. Traitement par lots : Jusqu’à 75 objets au total, tous attributes, events et purchases confondus, par requête API. Les clients soumis aux anciennes limites de débit peuvent inclure jusqu’à 75 objets par tableau, indépendamment. Pour plus d’informations, consultez Traitement par lots des requêtes User Track.Limites pour les utilisateurs actifs mensuels CY 24-25, Universal MAU, Web MAU et Mobile MAU : Consultez Limites des utilisateurs actifs mensuels CY 24-25. |
/users/track/status |
1 500 requêtes par minute. |
/users/export/ids |
Si votre onboarding a eu lieu le 22 août 2024 ou après : 250 requêtes par minute. Si votre onboarding a eu lieu avant le 22 août 2024 : 2 500 requêtes par minute. |
/users/delete/users/alias/new/users/alias/update/users/identify/users/merge |
20 000 requêtes par minute, partagées entre les endpoints. |
/users/external_id/rename |
1 000 requêtes par minute. |
/users/external_id/remove |
1 000 requêtes par minute. |
/events/list |
1 000 requêtes par heure, partagées avec l’endpoint /purchases/product_list. |
/purchases/product_list |
1 000 requêtes par heure, partagées avec l’endpoint /events/list. |
/campaigns/data_series |
50 000 requêtes par minute. |
/messages/send/campaigns/trigger/send/canvas/trigger/send/campaigns/trigger/schedule/create/canvas/trigger/schedule/create |
Pour les appels de diffusion (lorsque vous ciblez largement des Segments, des filtres ou une audience connectée), 250 requêtes par minute toutes audiences confondues, et 10 requêtes par minute par audience unique (la première limite atteinte s’applique). Sinon, lorsque vous ciblez des destinataires individuels, la requête est comptabilisée dans la limite de débit partagée de 250 000 requêtes par heure. |
/sends/id/create |
100 requêtes par jour. |
/subscription/status/set |
5 000 requêtes par minute. |
/preference_center/v1/{preferenceCenterExternalId}/url/{userId}/preference_center/v1/list/preference_center/v1/{preferenceCenterExternalId} |
1 000 requêtes par minute. |
/preference_center/v1/preference_center/v1/{preferenceCenterExternalId} |
10 requêtes par minute. |
/catalogs/{catalog_name}/catalogs/catalogs |
50 requêtes par minute, partagées entre les endpoints. |
/catalogs/{catalog_name}/items/catalogs/{catalog_name}/items/catalogs/{catalog_name}/items |
16 000 requêtes par minute, partagées entre les 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 requêtes par minute, partagées entre les endpoints. |
/catalogs/{catalog_name}/fields/{field_name}/catalogs/{catalog_name}/fields/catalogs/{catalog_name}/selections/{selection_name}/catalogs/{catalog_name}/selections |
50 requêtes par minute, partagées entre les endpoints. |
/scim/v2/Users/{id}/scim/v2/Users?filter={[email protected]}/scim/v2/Users/{id}/scim/v2/Users/{id}}/scim/v2/Users/ |
20 000 requêtes par jour et par entreprise, partagées entre les endpoints. |
/cdi/integrations |
50 requêtes par minute. |
/cdi/integrations/{integration_id}/sync |
20 requêtes par minute. |
/cdi/integrations/{integration_id}/job_sync_status |
100 requêtes par minute. |
/media_library/create |
100 requêtes par heure. |
/media_library/replace_file |
100 requêtes par heure. |
Requêtes avec des limites de débit partagées
Les requêtes suivantes sont soumises à une limite de débit de 250 000 requêtes par heure, partagée entre elles.
/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(uniquement pour les appels hors diffusion—ceux qui spécifientexternal_user_idsoualiases)/campaigns/trigger/schedule/create(uniquement pour les appels hors diffusion)/campaigns/trigger/schedule/delete/campaigns/trigger/schedule/update/canvas/data_series/canvas/data_summary/canvas/details/canvas/list/canvas/trigger/send(uniquement pour les appels hors diffusion)/canvas/trigger/schedule/create(uniquement pour les appels hors diffusion)/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(uniquement pour les appels hors diffusion)/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’est-ce qui est considéré comme une même audience unique ?
Cela s’applique aux endpoints suivants : /messages/send, /campaigns/trigger/send, /canvas/trigger/send, /campaigns/trigger/schedule/create et /canvas/trigger/schedule/create.
Pour ces endpoints, des requêtes de diffusion sont considérées comme ciblant la même audience unique lorsque tous les éléments suivants correspondent :
- La Campaign ou le Canvas déclenché (le
campaign_idou lecanvas_idde votre requête API, s’il est spécifié) - L’audience ciblée (les Segments ou les filtres, ou, pour les Campaigns API, le
segment_idde votre requête API) - Les filtres d’audience connectée (l’objet
audiencede votre requête API, s’il est spécifié)
Chaque combinaison unique de ces attributs compte comme une audience distincte : la limite de débit supplémentaire par audience unique s’applique donc à chaque combinaison de manière indépendante.
Traitement par lots des requêtes API
Les API de Braze sont conçues pour prendre en charge le traitement par lots. Grâce au traitement par lots, Braze peut ingérer un maximum de données en un seul appel API, ce qui vous évite de multiplier les appels. Pour Braze, traiter les données par lots est plus efficace que de les traiter un appel à la fois. Par exemple, gérer 1 000 appels API par lots consomme moins de ressources que gérer 75 000 appels individuels. Le traitement par lots est essentiel pour toute application susceptible de nécessiter plus de 75 000 appels par heure.
Les augmentations de limite de débit de l’API REST sont étudiées en fonction des besoins des clients qui utilisent les capacités de traitement par lots de l’API.
Traitement par lots des requêtes pour l’endpoint de création et de mise à jour des utilisateurs
Chaque requête /users/track peut contenir jusqu’à 75 objets au total, répartis entre attributes, events et purchases. Chaque objet peut mettre à jour un utilisateur. Un même profil utilisateur peut être mis à jour par plusieurs objets.
Anciennes limites de débit
Pour les clients soumis aux anciennes limites de débit, chaque tableau (attributes, events et purchases) peut contenir jusqu’à 75 objets indépendamment, soit un maximum combiné de 225 objets par requête.
Pour plus d’informations sur les limites de débit de /users/track, consultez POST : Créer et mettre à jour des utilisateurs.
Les requêtes envoyées à cet endpoint commencent généralement à être traitées dans l’ordre suivant :
- Attributs
- Événements
- Achats
Traitement par lots des requêtes vers les endpoints de messagerie
Une seule requête vers les endpoints de messagerie peut atteindre l’un des éléments suivants :
- Jusqu’à 50
external_idsspécifiques, chacun avec ses propres paramètres de message - Un Segment de n’importe quelle taille créé dans le tableau de bord de Braze, spécifié par son
segment_id - Les utilisateurs correspondant à des filtres d’audience supplémentaires de n’importe quelle taille, définis dans la requête sous la forme d’un objet audience connectée
Exemple de requête par lots
L’exemple suivant utilise external_id pour effectuer un seul appel API pour l’e-mail et le 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]"]
}
]
}
Surveiller vos limites de débit
Chaque requête API envoyée à Braze et soumise à la limitation du débit standard de la REST API renvoie les informations suivantes dans les en-têtes de la réponse :
| Nom de l’en-tête | Description |
|---|---|
X-RateLimit-Limit |
Le nombre maximum de requêtes que vous pouvez effectuer dans un intervalle donné (votre limite de débit). |
X-RateLimit-Remaining |
Le nombre de requêtes restantes dans la fenêtre de limite de débit en cours. |
X-RateLimit-Reset |
Le moment où la fenêtre de limite de débit en cours est réinitialisée, en secondes epoch UTC. |
Les endpoints qui ne sont pas soumis à la limitation du débit standard de la REST API, comme les endpoints d’e-mails transactionnels, ne sont pas pris en compte dans votre limite de débit globale de l’API externe et ne renvoient pas ces en-têtes.
Ces informations figurent volontairement dans l’en-tête de la réponse à la requête API plutôt que dans le tableau de bord de Braze. Votre système peut ainsi mieux réagir en temps réel lorsqu’il interagit avec notre API. Par exemple, si la valeur X-RateLimit-Remaining passe sous un certain seuil, vous pouvez ralentir vos requêtes. Si elle atteint zéro, vous pouvez suspendre les requêtes jusqu’à ce que le délai indiqué dans X-RateLimit-Reset soit écoulé.
Résolution des problèmes liés aux réponses 429 Too Many Requests
Si un endpoint renvoie une réponse HTTP 429 Too Many Requests parce que votre intégration a dépassé une limite de débit, utilisez les en-têtes de la réponse pour déterminer à quel moment réessayer :
- Suspendez les requêtes. Si la réponse inclut
X-RateLimit-Retry-After, attendez le nombre de secondes indiqué. Sinon, attendez l’horodatage epoch UTC indiqué dansX-RateLimit-Reset. - Reprenez les requêtes à un rythme plus faible. Envoyez moins de requêtes dans chaque fenêtre de limite de débit pour réduire le risque d’obtenir une nouvelle réponse
429. - Lorsque c’est possible, regroupez plusieurs mises à jour dans chaque requête. Pour
/users/track, respectez la limite d’objets par requête de votre compte. - Utilisez le tableau de bord d’utilisation de l’API pour repérer les pics de requêtes et les tendances des réponses
429.
Pour connaître les valeurs par défaut propres à chaque endpoint, consultez la section Limites de débit par type de requête.
Les en-têtes HTTP sont renvoyés entièrement en minuscules. Ce comportement est conforme au protocole HTTP/2, qui exige que tous les noms de champs d’en-tête soient en minuscules. Il diffère de HTTP/1.X, où les noms d’en-tête n’étaient pas sensibles à la casse, mais étaient couramment écrits avec des majuscules variées.
Si vous avez des questions sur les limites de l’API, contactez votre gestionnaire de la satisfaction client ou ouvrez un ticket d’assistance.
Vous pouvez utiliser le tableau de bord d’utilisation de l’API pour consulter le trafic entrant et le comparer à vos limites de débit.
Délai optimal entre les endpoints
Nous vous recommandons de prévoir un délai de 5 minutes entre les appels consécutifs aux endpoints afin de limiter les erreurs.
Il est essentiel de connaître le délai optimal entre les endpoints lorsque vous effectuez des appels consécutifs à l’API de Braze. Des problèmes surviennent lorsque des endpoints dépendent du traitement réussi d’autres endpoints : s’ils sont appelés trop tôt, ils peuvent générer des erreurs. Par exemple, si vous attribuez un alias à des utilisateurs via notre endpoint /user/alias/new, puis utilisez cet alias pour envoyer un événement personnalisé via notre endpoint /users/track, combien de temps devez-vous attendre ?
Dans des conditions normales, la cohérence à terme de nos données s’établit en 10 à 100 ms (1/10 de seconde). Cependant, il peut arriver que cette cohérence prenne plus de temps. Nous vous recommandons donc de prévoir un délai de 5 minutes entre les appels successifs pour réduire au maximum le risque d’erreur.
Limites de taille du payload
Les requêtes API de Braze sont soumises à des limites de taille du payload, distinctes des limites de débit. La plupart des endpoints acceptent des corps de requête jusqu’à 4 Mo. Lorsqu’une requête dépasse la limite applicable, Braze peut la rejeter avec une erreur HTTP 413 Request Entity Too Large ou HTTP 400 Bad Request, selon l’endpoint.
L’endpoint /users/track/bulk a une limite de payload de 2 Mo et renvoie une erreur HTTP 400 lorsque le corps de la requête dépasse cette limite. Pour connaître les limites propres à chaque endpoint et la gestion des erreurs, consultez la section Endpoints de données utilisateur.
Réinitialisation de la limite de débit
Les limites de débit se réinitialisent au début de chaque heure, et non sur une fenêtre glissante. Par exemple, si la limite est de 250 000 requêtes par heure, vous pouvez effectuer 50 000 requêtes entre 22 h et 22 h 59, puis 250 000 autres requêtes entre 23 h et 23 h 59, car le compteur se réinitialise au début de chaque heure.