Rate-Limits
Die API-Infrastruktur von Braze ist darauf ausgelegt, große Datenmengen für unsere gesamte Kundenbasis 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, nicht durch böswillige Angriffe. Rate-Limits stellen sicher, dass solche Fehler unseren Kund:innen keine Ressourcen der Braze-API entziehen. Wenn in einem bestimmten Zeitraum 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, bei API-Aufrufen sinnvolle Limits einzuhalten, um Schäden oder Missbrauch zu vermeiden.
Rate-Limits nach Anfragetyp
Im Folgenden finden Sie die Standard-Rate-Limits der API für verschiedene Anfragetypen. Diese Standardlimits können auf Anfrage erhöht werden. Weitere Informationen erhalten Sie von Ihrem Customer-Success-Manager.
Anfragen mit unterschiedlichen Rate-Limits
| Anfragetyp | Standard-Rate-Limit der API |
|---|---|
/users/track |
Anfragen: Die 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äß Ihren Vertragsbedingungen konfiguriert. Bei Fragen zu Ihren Limits wenden Sie sich an den Braze-Support oder Ihren Customer-Success-Manager. Batching: Bis zu 75 Objekte insgesamt über attributes, events und purchases hinweg pro API-Anfrage. Kund:innen mit Legacy-Rate-Limits können bis zu 75 Objekte pro Array unabhängig voneinander einschließen. 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 Limits für Monthly Active Users CY 24-25. |
/users/track/status |
1.500 Anfragen pro Minute. |
/users/export/ids |
Wenn Ihr Onboarding am oder nach dem 22. August 2024 erfolgt ist: 250 Anfragen pro Minute. Wenn Ihr Onboarding vor dem 22. August 2024 erfolgt ist: 2.500 Anfragen pro Minute. |
/users/delete/users/alias/new/users/alias/update/users/identify/users/merge |
20.000 Anfragen pro Minute, gemeinsam für alle diese Endpunkte. |
/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, gemeinsam mit dem Endpunkt /purchases/product_list. |
/purchases/product_list |
1.000 Anfragen pro Stunde, gemeinsam 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 (beim breiten Targeting von Segmenten, Filtern oder einer verbundenen Zielgruppe) gelten 250 Anfragen pro Minute über alle Zielgruppen hinweg und 10 Anfragen pro Minute pro eindeutiger Zielgruppe (je nachdem, welches Limit zuerst erreicht wird). Andernfalls, beim Targeting einzelner Empfänger:innen, wird die Anfrage auf das gemeinsame Rate-Limit von 250.000 Anfragen pro Stunde angerechnet. |
/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, gemeinsam für alle diese Endpunkte. |
/catalogs/{catalog_name}/items/catalogs/{catalog_name}/items/catalogs/{catalog_name}/items |
16.000 Anfragen pro Minute, gemeinsam für alle diese Endpunkte. |
/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, gemeinsam für alle diese Endpunkte. |
/catalogs/{catalog_name}/fields/{field_name}/catalogs/{catalog_name}/fields/catalogs/{catalog_name}/selections/{selection_name}/catalogs/{catalog_name}/selections |
50 Anfragen pro Minute, gemeinsam für alle diese Endpunkte. |
/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 und Unternehmen, gemeinsam für alle diese Endpunkte. |
/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
Für die folgenden Anfragen gilt ein gemeinsames 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—also 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.
Bei diesen Endpunkten gelten Broadcast-Anfragen als auf dieselbe eindeutige Zielgruppe ausgerichtet, wenn alle folgenden Punkte übereinstimmen:
- Die getriggerte Campaign oder das getriggerte Canvas (die
campaign_idodercanvas_idin Ihrer API-Anfrage, sofern angegeben) - Die anvisierte Zielgruppe (die Segmente oder Filter bzw. bei API-Campaigns die
segment_idin Ihrer API-Anfrage) - Die Filter für verbundene Zielgruppen (das Objekt
audiencein Ihrer API-Anfrage, sofern angegeben)
Jede eindeutige Kombination dieser Attribute zählt als eigene Zielgruppe. Das zusätzliche Rate-Limit pro eindeutiger Zielgruppe gilt daher für jede Kombination unabhängig.
Batching von API-Anfragen
Die APIs von Braze unterstützen Batching. Damit kann Braze so viele Daten wie möglich in einem einzigen API-Aufruf entgegennehmen, sodass Sie nicht viele einzelne API-Aufrufe durchführen müssen. Für Braze ist es effizienter, Daten in Batches zu verarbeiten als Aufruf für Aufruf. So benötigt beispielsweise die Verarbeitung von 1.000 gebündelten API-Aufrufen weniger Ressourcen als die Verarbeitung von 75.000 einzelnen Aufrufen. Batching ist besonders wichtig für alle Anwendungen, die mehr als 75.000 Aufrufe pro Stunde benötigen.
Erhöhungen der Rate-Limits für die REST API werden bei Bedarf für Kund:innen geprüft, die die Batching-Funktionen der API nutzen.
Batching von Anfragen an den Endpunkt zum Erstellen und Aktualisieren von Nutzer:innen
Jede /users/track-Anfrage kann insgesamt bis zu 75 Objekte enthalten, zusammengerechnet über attributes, events und purchases. Jedes Objekt kann eine:n Nutzer:in aktualisieren. Ein einzelnes Nutzerprofil kann durch mehrere Objekte aktualisiert werden.
Legacy-Rate-Limits
Für Kund:innen mit Legacy-Rate-Limits kann jedes Array (attributes, events und purchases) unabhängig voneinander bis zu 75 Objekte enthalten, also insgesamt bis zu 225 Objekte pro Anfrage.
Weitere Informationen zu den Rate-Limits von /users/track finden Sie unter POST: Nutzer:innen erstellen und aktualisieren.
Anfragen an diesen Endpunkt werden in der Regel in folgender Reihenfolge verarbeitet:
- Attribute
- Events
- Käufe
Batching von Anfragen an Messaging-Endpunkte
Eine einzelne Anfrage an die Messaging-Endpunkte kann eine der folgenden Zielgruppen erreichen:
- Bis zu 50 bestimmte
external_ids, jeweils mit individuellen Nachrichtenparametern - Ein im Braze-Dashboard erstelltes Segment beliebiger Größe, angegeben über seine
segment_id - Nutzer:innen beliebiger Anzahl, die zusätzlichen Zielgruppenfiltern entsprechen, die in der Anfrage als Connected-Audience-Objekt definiert sind
Beispiel für eine Batch-Anfrage
Im folgenden Beispiel wird external_id verwendet, um einen einzigen 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]"]
}
]
}
Überwachung Ihrer Rate-Limits
Jede API-Anfrage an Braze, die dem standardmäßigen Rate-Limiting der REST API unterliegt, gibt in den Antwort-Headern die folgenden Informationen zurück:
| Header-Name | Beschreibung |
|---|---|
X-RateLimit-Limit |
Die maximale Anzahl an 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-Epochensekunden. |
Endpunkte, die das standardmäßige Rate-Limiting der REST API umgehen, wie etwa die Endpunkte für Transaktions-E-Mails, werden nicht auf Ihr gesamtes externes API-Rate-Limit angerechnet und geben diese Header nicht zurück.
Diese Informationen sind bewusst im Header der Antwort auf die API-Anfrage enthalten und nicht im Braze-Dashboard. So kann Ihr System in Echtzeit besser reagieren, während Sie mit unserer API interagieren. Wenn beispielsweise der Wert X-RateLimit-Remaining unter einen bestimmten Schwellenwert fällt, sollten Sie Ihre Anfragen gegebenenfalls verlangsamen. Erreicht er null, sollten Sie Anfragen eventuell pausieren, bis der in X-RateLimit-Reset angegebene Zeitpunkt verstrichen ist.
Fehlerbehebung bei 429 Too Many Requests-Antworten
Wenn ein Endpunkt eine HTTP-Antwort 429 Too Many Requests zurückgibt, weil Ihre Integration ein Rate-Limit überschritten hat, ermitteln Sie anhand der Antwort-Header, wann Sie es erneut versuchen sollten:
- Pausieren Sie Anfragen. Wenn die Antwort
X-RateLimit-Retry-Afterenthält, warten Sie die angegebene Anzahl an Sekunden. Andernfalls warten Sie bis zum UTC-Epochenzeitstempel inX-RateLimit-Reset. - Nehmen Sie Anfragen mit einer geringeren Rate wieder auf. Senden Sie weniger Anfragen pro Rate-Limit-Fenster, um die Wahrscheinlichkeit einer weiteren
429-Antwort zu verringern. - Fassen Sie, sofern unterstützt, mehrere Updates in einer Anfrage zusammen. Beachten Sie für
/users/trackdas Limit für Anfrageobjekte für Ihr Konto. - Nutzen Sie das Dashboard zur API-Nutzung, um Spitzen bei Anfragen und Trends bei
429-Antworten zu erkennen.
Endpunktspezifische Standardwerte finden Sie unter Rate-Limits nach Anfragetyp.
HTTP-Header werden durchgängig in Kleinbuchstaben zurückgegeben. Dieses Verhalten entspricht dem HTTP/2-Protokoll, das vorschreibt, dass alle Header-Feldnamen kleingeschrieben sein müssen. Dies unterscheidet sich von HTTP/1.X, bei dem Header-Namen nicht zwischen Groß- und Kleinschreibung unterschieden, aber häufig in unterschiedlicher Schreibweise angegeben wurden.
Wenn Sie Fragen zu API-Limits haben, wenden Sie sich an Ihre:n Customer-Success-Manager:in oder eröffnen Sie ein Support-Ticket.
Mit dem Dashboard zur API-Nutzung können Sie eingehenden Traffic anzeigen und mit Ihren Rate-Limits vergleichen.
Optimale Verzögerung zwischen Endpunkten
Wir empfehlen, zwischen aufeinanderfolgenden Endpunkt-Aufrufen eine Verzögerung von 5 Minuten einzuplanen, um Fehler zu minimieren.
Die optimale Verzögerung zwischen Endpunkten zu kennen, ist bei aufeinanderfolgenden Aufrufen der Braze-API entscheidend. Probleme entstehen, wenn Endpunkte von der erfolgreichen Verarbeitung anderer Endpunkte abhängen und bei einem zu frühen Aufruf Fehler auslösen können. Wenn Sie beispielsweise Nutzer:innen über unseren Endpunkt /user/alias/new einen Alias zuweisen und diesen Alias anschließend verwenden, um über unseren Endpunkt /users/track ein angepasstes Event zu senden – wie lange sollten Sie warten?
Unter normalen Bedingungen dauert es 10–100 ms (1/10 Sekunde), bis unsere Daten letztendlich konsistent sind. In manchen Fällen kann es jedoch länger dauern, bis diese Konsistenz erreicht ist. Daher empfehlen wir, zwischen aufeinanderfolgenden Aufrufen eine Verzögerung von 5 Minuten einzuplanen, um die Fehlerwahrscheinlichkeit zu minimieren.
Größenbeschränkungen für Payloads
Für Braze API-Anfragen gelten Größenbeschränkungen für Payloads, die unabhängig von Rate-Limits sind. Die meisten Endpunkte akzeptieren Anfrage-Bodys bis zu 4 MB. Wenn eine Anfrage die jeweilige Beschränkung überschreitet, kann Braze sie je nach Endpunkt mit HTTP 413 Request Entity Too Large oder HTTP 400 Bad Request ablehnen.
Für den Endpunkt /users/track/bulk gilt eine Payload-Beschränkung von 2 MB. Er gibt HTTP 400 zurück, wenn der Anfrage-Body diese Beschränkung überschreitet. Endpunktspezifische Beschränkungen und Informationen zur Fehlerbehandlung finden Sie unter Endpunkte für Nutzerdaten.
Zurücksetzen der Rate-Limits
Rate-Limits werden zur vollen Stunde zurückgesetzt, nicht in einem gleitenden Zeitfenster. Wenn das Limit beispielsweise bei 250.000 Anfragen pro Stunde liegt, könnten Sie zwischen 22:00 und 22:59 Uhr 50.000 Anfragen stellen und zwischen 23:00 und 23:59 Uhr weitere 250.000 Anfragen, da der Zähler zu Beginn jeder Stunde zurückgesetzt wird.