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 Standard-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 über attributes, events und purchases pro API-Anfrage. Kund:innen mit älteren 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 Monthly Active Users CY 24-25 Limits. |
/users/track/status |
1.500 Anfragen pro Minute. |
/users/export/ids |
Wenn Ihr Onboarding am oder nach dem 22. August 2024 stattfand: 250 Anfragen pro Minute. Wenn Ihr Onboarding vor dem 22. August 2024 stattfand: 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 breitem Targeting auf Segmente, Filter oder eine verbundene Zielgruppe) 250 Anfragen pro Minute über alle Zielgruppen und 10 Anfragen pro Minute pro eindeutige Zielgruppe (je nachdem, welches Limit zuerst erreicht wird). Andernfalls, wenn einzelne Empfänger:innen angesprochen werden, wird die Anfrage in das geteilte Rate-Limit von 250.000 Anfragen pro Stunde einbezogen. |
/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 geteilten Rate-Limits
Die folgenden Anfragen haben ein Rate-Limit von 250.000 Anfragen pro Stunde, das zwischen ihnen geteilt wird.
/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 Kriterien übereinstimmen:
- Die ausgelöste Campaign oder das ausgelöste Canvas (die
campaign_idodercanvas_idin Ihrer API-Anfrage, falls angegeben) - Die angesprochene Zielgruppe (die Segmente oder Filter bzw. bei API-Campaigns die
segment_idin Ihrer API-Anfrage) - Die verbundenen Zielgruppenfilter (das
audience-Objekt in Ihrer API-Anfrage, falls angegeben)
Jede eindeutige Kombination dieser Attribute zählt als separate Zielgruppe, sodass das zusätzliche Rate-Limit pro eindeutiger Zielgruppe für jede Kombination unabhängig gilt.
API-Anfragen bündeln
Braze-APIs unterstützen das Bündeln (Batching) von Anfragen. Mit dem Batching kann Braze so viele Daten wie möglich in einem einzigen API-Aufruf aufnehmen, sodass Sie nicht viele einzelne API-Aufrufe machen müssen. Für Braze ist es effizienter, Daten gebündelt zu verarbeiten, als jeden Aufruf einzeln abzuarbeiten. Beispielsweise erfordert die Verarbeitung von 1.000 gebündelten API-Aufrufen weniger Ressourcen als die Verarbeitung von 75.000 einzelnen Aufrufen. Das Batching ist äußerst wichtig für jede Anwendung, die möglicherweise mehr als 75.000 Aufrufe pro Stunde benötigt.
Erhöhungen des REST-API-Rate-Limits werden bedarfsgerecht für Kund:innen in Betracht gezogen, die die API-Batching-Funktionen nutzen.
Anfragen für den Endpunkt „Nutzer:innen erstellen und aktualisieren“ bündeln
Jede /users/track-Anfrage kann insgesamt bis zu 75 Objekte über attributes, events und purchases hinweg enthalten. 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 voneinander bis zu 75 Objekte enthalten, was insgesamt maximal 225 Objekte pro Anfrage ergibt.
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
Anfragen an Messaging-Endpunkte bündeln
Eine einzelne Anfrage an die Messaging-Endpunkte kann eine der folgenden Zielgruppen erreichen:
- Bis zu 50 spezifische
external_idsmit jeweils 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 gebündelte Anfrage
Das folgende Beispiel verwendet external_id, 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]"]
}
]
}
Ü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 sind absichtlich 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 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.
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, verwenden Sie die Antwort-Header, um zu bestimmen, wann ein erneuter Versuch erfolgen soll:
- Pausieren Sie Anfragen. Wenn die Antwort
X-RateLimit-Retry-Afterenthält, warten Sie die angegebene Anzahl von Sekunden. Andernfalls warten Sie bis zum UTC-Epoch-Zeitstempel inX-RateLimit-Reset. - Setzen Sie Anfragen mit einer niedrigeren Rate fort. Senden Sie weniger Anfragen innerhalb jedes Rate-Limit-Fensters, um die Wahrscheinlichkeit einer weiteren
429-Antwort zu verringern. - Kombinieren Sie, wo unterstützt, mehrere Updates in jeder Anfrage. Befolgen Sie für
/users/trackdas Anfrageobjekt-Limit für Ihr Konto. - Verwenden Sie das API-Nutzungs-Dashboard, um Anfrage-Spitzen und
429-Antworttrends zu identifizieren.
Für endpunktspezifische Standardwerte siehe Rate-Limits nach Anfragetyp.
HTTP-Header werden ausschließlich 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, wo Header-Namen nicht zwischen Groß- und Kleinschreibung unterschieden, aber häufig in verschiedenen Schreibweisen angegeben 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, eine Verzögerung von 5 Minuten zwischen aufeinanderfolgenden Endpunktaufrufen einzuplanen, um Fehler zu minimieren.
Das Verständnis der optimalen Verzögerung zwischen Endpunkten ist entscheidend, wenn aufeinanderfolgende Aufrufe an die Braze-API erfolgen. Probleme entstehen, wenn Endpunkte von der erfolgreichen Verarbeitung anderer Endpunkte abhängen und bei einem zu frühen Aufruf Fehler auslösen könnten. Wenn Sie beispielsweise Nutzer:innen über unseren /user/alias/new-Endpunkt einen Alias zuweisen und dann diesen Alias verwenden, 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 die Eventual Consistency unserer Daten 10–100 ms (1/10 Sekunde). Es kann jedoch Fälle geben, in denen diese Konsistenz länger dauert, weshalb wir empfehlen, eine Verzögerung von 5 Minuten zwischen aufeinanderfolgenden Aufrufen einzuplanen, um die Fehlerwahrscheinlichkeit zu minimieren.
Begrenzungen der Payload-Größe
Braze-API-Anfragen unterliegen Begrenzungen der Payload-Größe, die unabhängig von den Rate-Limits gelten. Die meisten Endpunkte akzeptieren Anfragekörper 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, abhängig vom 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önnen 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 jeder vollen Stunde zurückgesetzt wird.