Rate-Limits
Die API-Infrastruktur von Braze ist darauf ausgelegt, große Datenmengen für unsere Kund:innen zu verarbeiten. Zu diesem Zweck setzen wir API Rate-Limits pro Workspace durch.
Ein Rate-Limit ist die Anzahl der Anfragen, die die API in einem bestimmten Zeitraum empfangen kann. Viele lastbasierte Denial-of-Service-Vorfälle in großen Systemen sind unbeabsichtigt – sie werden durch Fehler in Software oder Konfigurationen verursacht und nicht durch böswillige Angriffe. Rate-Limits stellen sicher, dass unseren Kund:innen durch solche Fehler keine Braze API-Ressourcen vorenthalten werden. Wenn in einem bestimmten Zeitrahmen zu viele Anfragen gesendet werden, erhalten Sie möglicherweise Fehlerantworten mit dem Statuscode 429, der anzeigt, dass das Rate-Limit erreicht wurde.
API Rate-Limits können sich je nach ordnungsgemäßer Nutzung unseres Systems ändern. Wir empfehlen vernünftige Grenzen bei API-Aufrufen, um Schäden oder Missbrauch zu vermeiden.
Rate-Limits nach Anfragetyp
In der folgenden Übersicht finden Sie die standardmäßigen API-Rate-Limits für verschiedene Anfragetypen. Diese Standardlimits können auf Anfrage erhöht werden. Wenden Sie sich an Ihren Customer-Success-Manager, um weitere Informationen zu erhalten.
Anfragen mit unterschiedlichen Rate-Limits
| Anfragetyp | Standard-API-Rate-Limit |
|---|---|
/users/track |
Anfragen: Rate-Limits variieren je nach Vertrag. Für Kund:innen, deren Preismodell Datenpunkte umfasst, wendet Braze ein Burst-Limit von 3.000 Anfragen pro drei Sekunden an. Für alle anderen Kund:innen werden die Limits gemäß den Vertragsbedingungen konfiguriert. Wenden Sie sich bei Fragen zu Ihren Limits an den Braze-Support oder Ihren Customer-Success-Manager. Batching: Bis zu 75 Objekte insgesamt, kombiniert aus attributes, events und purchases, pro API-Anfrage. Kund:innen mit Legacy-Rate-Limits können bis zu 75 Objekte pro Array unabhängig voneinander einbeziehen. Weitere Informationen finden Sie unter Batching von User-Track-Anfragen.Limits für Monthly Active Users CY 24-25, Universal MAU, Web MAU und Mobile MAU: Siehe Monthly Active Users CY 24-25 Limits. |
/users/track/status |
1.500 Anfragen pro Minute. |
/users/export/ids |
Wenn Sie am oder nach dem 22. August 2024 ongeboardet wurden: 250 Anfragen pro Minute. Wenn Sie vor dem 22. August 2024 ongeboardet wurden: 2.500 Anfragen pro Minute. |
/users/delete/users/alias/new/users/alias/update/users/identify/users/merge |
20.000 Anfragen pro Minute, geteilt zwischen den Endpunkten. |
/users/external_id/rename |
1.000 Anfragen pro Minute. |
/users/external_id/remove |
1.000 Anfragen pro Minute. |
/events/list |
1.000 Anfragen pro Stunde, geteilt mit dem Endpunkt /purchases/product_list. |
/purchases/product_list |
1.000 Anfragen pro Stunde, geteilt mit dem Endpunkt /events/list. |
/campaigns/data_series |
50.000 Anfragen pro Minute. |
/messages/send/campaigns/trigger/send/canvas/trigger/send/campaigns/trigger/schedule/create/canvas/trigger/schedule/create |
Für Broadcast-Aufrufe (bei breiter Ansprache von Segmenten, Filtern oder einer verbundenen Zielgruppe): 250 Anfragen pro Minute über alle Zielgruppen hinweg und 10 Anfragen pro Minute pro eindeutiger Zielgruppe (je nachdem, welches Limit zuerst erreicht wird). Andernfalls, wenn einzelne Empfänger:innen angesprochen werden, wird die Anfrage in das gemeinsame Rate-Limit von 250.000 Anfragen pro Stunde eingerechnet. |
/sends/id/create |
100 Anfragen pro Tag. |
/subscription/status/set |
5.000 Anfragen pro Minute. |
/preference_center/v1/{preferenceCenterExternalId}/url/{userId}/preference_center/v1/list/preference_center/v1/{preferenceCenterExternalId} |
1.000 Anfragen pro Minute. |
/preference_center/v1/preference_center/v1/{preferenceCenterExternalId} |
10 Anfragen pro Minute. |
/catalogs/{catalog_name}/catalogs/catalogs |
50 Anfragen pro Minute, geteilt zwischen den Endpunkten. |
/catalogs/{catalog_name}/items/catalogs/{catalog_name}/items/catalogs/{catalog_name}/items |
16.000 Anfragen pro Minute, geteilt zwischen den Endpunkten. |
/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 Anfragen pro Minute, geteilt zwischen den Endpunkten. |
/catalogs/{catalog_name}/fields/{field_name}/catalogs/{catalog_name}/fields/catalogs/{catalog_name}/selections/{selection_name}/catalogs/{catalog_name}/selections |
50 Anfragen pro Minute, geteilt zwischen den Endpunkten. |
/scim/v2/Users/{id}/scim/v2/Users?filter={[email protected]}/scim/v2/Users/{id}/scim/v2/Users/{id}}/scim/v2/Users/ |
20.000 Anfragen pro Tag, pro Unternehmen, geteilt zwischen den Endpunkten. |
/cdi/integrations |
50 Anfragen pro Minute. |
/cdi/integrations/{integration_id}/sync |
20 Anfragen pro Minute. |
/cdi/integrations/{integration_id}/job_sync_status |
100 Anfragen pro Minute. |
/media_library/create |
100 Anfragen pro Stunde. |
/media_library/replace_file |
100 Anfragen pro Stunde. |
Anfragen mit gemeinsamen Rate-Limits
Die folgenden Anfragen unterliegen einem gemeinsamen Rate-Limit von 250.000 Anfragen pro Stunde.
/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(nur für Nicht-Broadcast-Aufrufe—solche, dieexternal_user_idsoderaliasesangeben)/campaigns/trigger/schedule/create(nur für Nicht-Broadcast-Aufrufe)/campaigns/trigger/schedule/delete/campaigns/trigger/schedule/update/canvas/data_series/canvas/data_summary/canvas/details/canvas/list/canvas/trigger/send(nur für Nicht-Broadcast-Aufrufe)/canvas/trigger/schedule/create(nur für Nicht-Broadcast-Aufrufe)/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(nur für Nicht-Broadcast-Aufrufe)/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
Was zählt als dieselbe eindeutige Zielgruppe?
Dies gilt für die folgenden Endpunkte: /messages/send, /campaigns/trigger/send, /canvas/trigger/send, /campaigns/trigger/schedule/create und /canvas/trigger/schedule/create.
Für diese Endpunkte gelten Broadcast-Anfragen als auf dieselbe eindeutige Zielgruppe ausgerichtet, wenn alle folgenden Kriterien übereinstimmen:
- Die ausgelöste Campaign oder das ausgelöste Canvas (die
campaign_idodercanvas_idin Ihrer API-Anfrage, sofern angegeben) - Die angesprochene Zielgruppe (die Segmente oder Filter, bzw. für API-Campaigns die
segment_idin Ihrer API-Anfrage) - Die verbundenen Zielgruppenfilter (das
audience-Objekt in Ihrer API-Anfrage, sofern angegeben)
Jede eindeutige Kombination dieser Attribute zählt als separate Zielgruppe, sodass das zusätzliche Rate-Limit pro eindeutiger Zielgruppe unabhängig auf jede Kombination angewendet wird.
Batching von API-Anfragen
Braze-APIs unterstützen Batching. Durch Batching kann Braze so viele Daten wie möglich in einem einzigen API-Aufruf aufnehmen, sodass Sie nicht zahlreiche API-Aufrufe durchführen müssen. Es ist für Braze effizienter, Daten in Batches zu verarbeiten, als jeden Aufruf einzeln zu verarbeiten. Beispielsweise erfordert die Verarbeitung von 1.000 gebatchten API-Aufrufen weniger Ressourcen als die Verarbeitung von 75.000 einzelnen Aufrufen. Batching ist äußerst wichtig für jede Anwendung, die möglicherweise mehr als 75.000 Aufrufe pro Stunde benötigt.
Erhöhungen der REST-API-Rate-Limits werden bedarfsabhängig für Kund:innen geprüft, die die API-Batching-Funktionen nutzen.
Batching von Anfragen für den Endpunkt „Nutzer:innen erstellen und aktualisieren“
Jede /users/track-Anfrage kann bis zu 75 Objekte insgesamt enthalten, verteilt auf attributes, events und purchases. Jedes Objekt kann eine:n Nutzer:in aktualisieren. Ein einzelnes Nutzerprofil kann durch mehrere Objekte aktualisiert werden.
Ältere Rate-Limits
Für Kund:innen mit älteren Rate-Limits kann jedes Array (attributes, events und purchases) unabhängig bis zu 75 Objekte enthalten, was einem kombinierten Maximum von bis zu 225 Objekten pro Anfrage entspricht.
Weitere Informationen zu /users/track-Rate-Limits finden Sie unter POST: Nutzer:innen erstellen und aktualisieren.
Anfragen an diesen Endpunkt werden im Allgemeinen in dieser Reihenfolge verarbeitet:
- Attribute
- Events
- Käufe
Batching von Messaging-Endpunkt-Anfragen
Eine einzelne Anfrage an die Messaging-Endpunkte kann eine der folgenden Optionen erreichen:
- Bis zu 50 spezifische
external_ids, jeweils mit individuellen Nachrichtenparametern - Ein Segment beliebiger Größe, das im Braze-Dashboard erstellt wurde und über seine
segment_idangegeben wird - Nutzer:innen, die zusätzlichen Zielgruppenfiltern beliebiger Größe entsprechen, die in der Anfrage als Connected Audience-Objekt definiert sind
Beispiel für eine Batch-Anfrage
Das folgende Beispiel verwendet external_id, um einen API-Aufruf für E-Mail und SMS durchzuführen.
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]"]
}
]
}
Überwachen Ihrer Rate-Limits
Jede einzelne API-Anfrage, die an Braze gesendet wird, gibt die folgenden Informationen in den Antwort-Headern zurück:
| Header-Name | Beschreibung |
|---|---|
X-RateLimit-Limit |
Die maximale Anzahl von Anfragen, die Sie in einem bestimmten Intervall stellen können (Ihr Rate-Limit). |
X-RateLimit-Remaining |
Die Anzahl der verbleibenden Anfragen im aktuellen Rate-Limit-Fenster. |
X-RateLimit-Reset |
Der Zeitpunkt, zu dem das aktuelle Rate-Limit-Fenster zurückgesetzt wird, in UTC-Epoch-Sekunden. |
Diese Informationen werden absichtlich im Header der Antwort auf die API-Anfrage statt im Braze-Dashboard bereitgestellt. So kann Ihr System in Echtzeit besser reagieren, während Sie mit unserer API interagieren. Wenn beispielsweise der Wert von X-RateLimit-Remaining unter einen bestimmten Schwellenwert fällt, möchten Sie möglicherweise den Versand verlangsamen, um sicherzustellen, dass alle Transaktions-E-Mails zugestellt werden. Oder wenn er null erreicht, möchten Sie möglicherweise den gesamten Versand pausieren, bis die in X-RateLimit-Reset angegebene Zeit abgelaufen ist.
HTTP-Header werden vollständig in Kleinbuchstaben zurückgegeben. Dieses Verhalten entspricht dem HTTP/2-Protokoll, das vorschreibt, dass alle Header-Feldnamen in Kleinbuchstaben geschrieben sein müssen. Dies unterscheidet sich von HTTP/1.X, bei dem Header-Namen nicht zwischen Groß- und Kleinschreibung unterschieden, aber üblicherweise in verschiedenen Schreibweisen geschrieben wurden.
Wenn Sie Fragen zu API-Limits haben, wenden Sie sich an Ihren Customer-Success-Manager oder eröffnen Sie ein Support-Ticket.
Sie können das API-Nutzungs-Dashboard verwenden, um eingehenden Traffic anzuzeigen und mit Ihren Rate-Limits zu vergleichen.
Optimale Verzögerung zwischen Endpunkten
Wir empfehlen, zwischen aufeinanderfolgenden Endpunkt-Aufrufen eine Verzögerung von 5 Minuten einzuplanen, um Fehler zu minimieren.
Das Verständnis der optimalen Verzögerung zwischen Endpunkten ist entscheidend, wenn Sie aufeinanderfolgende Aufrufe an die Braze-API senden. Probleme treten auf, wenn Endpunkte von der erfolgreichen Verarbeitung anderer Endpunkte abhängen und bei zu frühem Aufruf Fehler verursachen könnten. Wenn Sie beispielsweise Nutzer:innen über unseren /user/alias/new-Endpunkt einen Alias zuweisen und dann diesen Alias nutzen, um über unseren /users/track-Endpunkt ein angepasstes Event zu senden – wie lange sollten Sie warten?
Unter normalen Bedingungen beträgt die Zeit für unsere Eventual Consistency 10–100 ms (1/10 Sekunde). Es kann jedoch Fälle geben, in denen diese Konsistenz länger dauert. Daher empfehlen wir, zwischen aufeinanderfolgenden Aufrufen eine Verzögerung von 5 Minuten einzuplanen, um die Fehlerwahrscheinlichkeit zu minimieren.
Beschränkungen der Payload-Größe
Braze-API-Anfragen unterliegen Beschränkungen der Payload-Größe, die unabhängig von Rate-Limits gelten. Die meisten Endpunkte akzeptieren Anfragekörper von bis zu 4 MB. Wenn eine Anfrage das geltende Limit überschreitet, kann Braze sie mit HTTP 413 Request Entity Too Large oder HTTP 400 Bad Request ablehnen, je nach Endpunkt.
Der Endpunkt /users/track/bulk hat ein Payload-Limit von 2 MB und gibt HTTP 400 zurück, wenn der Anfragekörper dieses Limit überschreitet. Informationen zu endpunktspezifischen Limits und zur Fehlerbehandlung finden Sie unter Nutzerdaten-Endpunkte.
Zurücksetzen der Rate-Limits
Rate-Limits werden zur vollen Stunde zurückgesetzt und nicht in einem rollierenden Zeitfenster. Wenn das Limit beispielsweise 250.000 Anfragen pro Stunde beträgt, könnten Sie zwischen 22:00 Uhr und 22:59 Uhr 50.000 Anfragen und zwischen 23:00 Uhr und 23:59 Uhr weitere 250.000 Anfragen senden, da der Zähler zu Beginn jeder vollen Stunde zurückgesetzt wird.