Limites de débit
L’infrastructure API de Braze est conçue pour gérer des volumes élevés de données sur l’ensemble de notre base de clients. C’est pourquoi nous appliquons des limites de débit à 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. De nombreux incidents de déni de service liés à la charge dans les grands systèmes sont involontaires — causés par des erreurs dans les logiciels ou les configurations — et non par des attaques malveillantes. Les limites de débit garantissent que de telles erreurs ne privent pas nos clients des ressources de l’API de Braze. Si trop de requêtes sont envoyées dans un délai donné, vous risquez de recevoir des réponses d’erreur avec un code d’état 429, indiquant 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 encourageons à définir des limites raisonnables lors de vos appels API afin d’éviter tout dommage ou toute mauvaise utilisation.
Limites de débit par type de requête
Consultez les informations ci-dessous pour connaître les limites de débit par défaut de l’API selon le type de requête. Ces limites 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 l’assistance Braze ou votre gestionnaire de la satisfaction client. Traitement par lots : Jusqu’à 75 objets au total, tous types confondus ( attributes, events et purchases), par requête API. Les clients soumis aux anciennes limites de débit peuvent inclure jusqu’à 75 objets par tableau, indépendamment. Pour en savoir plus, 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 vous avez été intégré le 22 août 2024 ou après : 250 requêtes par minute. Si vous avez été intégré 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 (ciblage large de Segments, de filtres ou d’une audience connectée), 250 requêtes par minute pour l’ensemble des audiences 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 incluse 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 la 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, les 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.
Regroupement des requêtes API
Les API de Braze sont conçues pour prendre en charge le regroupement des requêtes (batching). Grâce au regroupement, Braze peut recevoir un maximum de données en un seul appel API, ce qui vous évite de multiplier les appels. Il est plus efficace pour Braze de traiter les données par lots qu’un appel à la fois. Par exemple, traiter 1 000 appels API groupés nécessite moins de ressources que traiter 75 000 appels individuels. Le regroupement est essentiel pour toute application susceptible de nécessiter plus de 75 000 appels par heure.
Les augmentations de la limite de débit de la REST API sont envisagées en fonction des besoins des clients qui utilisent les capacités de regroupement de l’API.
Regroupement des requêtes pour l’endpoint Créer et mettre à 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
Regroupement des requêtes pour les endpoints de messagerie
Une seule requête envoyée aux endpoints de messagerie peut atteindre l’une des cibles suivantes :
- 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, quelle que soit leur taille, définis dans la requête sous la forme d’un objet audience connectée
Exemple de requête groupée
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 maximal 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 actuelle. |
X-RateLimit-Reset |
L’heure à laquelle la fenêtre de limite de débit actuelle 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-mail transactionnel, ne sont pas comptabilisés dans votre limite de débit globale de l’API externe et ne renvoient pas ces en-têtes.
Ces informations sont volontairement incluses 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 lorsque vous interagissez 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 l’heure indiquée dans X-RateLimit-Reset soit atteinte.
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 quand 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’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 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 impose que tous les noms de champs d’en-tête soient en minuscules. C’est une différence avec HTTP/1.X, où les noms d’en-tête n’étaient pas sensibles à la casse mais s’écrivaient couramment avec diverses capitalisations.
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 visualiser 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 deux appels d’endpoints consécutifs 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 que vous 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/10e de seconde). Cependant, il arrive que cette cohérence prenne plus de temps. Nous vous recommandons donc de prévoir un délai de 5 minutes entre deux appels successifs pour réduire au minimum le risque d’erreur.
Limites de taille du payload
Les requêtes de l’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 allant 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 00 et 22 h 59, puis 250 000 autres requêtes entre 23 h 00 et 23 h 59, car le compteur se réinitialise au début de chaque heure.