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
Le tableau ci-dessous présente les limites de débit par défaut de l’API pour chaque type de requête. Vous pouvez demander une augmentation de ces limites. 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 dépendent de votre contrat. Si votre 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 conditions 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 tableaux 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 la section Traitement par lots des requêtes User Track.Limites pour Monthly Active Users CY 24-25, Universal MAU, Web MAU et Mobile MAU : Consultez la section Limites Monthly Active Users 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 de manière large des Segments, des filtres ou 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 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 constitue une même audience unique ?
Cette règle 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 sont identiques :
- 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 correspond à 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 à ce mode de traitement, Braze peut recevoir un maximum de données en un seul appel API, ce qui vous évite de multiplier les appels. Pour Braze, traiter des données par lots est plus efficace que de les traiter un appel à la fois. Par exemple, 1 000 appels API groupés consomment moins de ressources que 75 000 appels individuels. Le traitement par lots est essentiel pour toute application susceptible de dépasser 75 000 appels par heure.
Les augmentations de la limite de débit de la REST API sont étudiées au cas par cas pour les clients qui utilisent les capacités de traitement par lots de l’API.
Traitement par lots 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 en savoir plus sur les limites de débit de /users/track, consultez POST : Créer et mettre à jour des utilisateurs.
Les requêtes adressées à cet endpoint commencent généralement à être traitées dans l’ordre suivant :
- Attributs
- Événements
- Achats
Traitement par lots des requêtes pour les endpoints d’envoi de messages
Une seule requête vers les endpoints d’envoi de messages 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 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 l’API REST 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 sur 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 se réinitialise, en secondes epoch UTC. |
Les endpoints qui échappent à la limitation du débit standard de l’API REST, 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 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 passée.
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 par rapport à HTTP/1.X, où les noms d’en-tête n’étaient pas sensibles à la casse, mais étaient couramment écrits avec diverses majuscules.
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 des appels consécutifs aux endpoints afin de minimiser les erreurs.
Il est essentiel de comprendre 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, le délai de cohérence éventuelle de nos données est de 10 à 100 ms (1/10 de seconde). Cependant, dans certains cas, cette cohérence peut prendre plus de temps. Nous vous recommandons donc de prévoir un délai de 5 minutes entre les appels successifs afin de minimiser le risque d’erreur.
Limites de taille des payloads
Les requêtes de l’API de Braze sont soumises à des limites de taille de 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 et la gestion des erreurs propres à chaque endpoint, consultez Endpoints des 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.