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
Im Folgenden finden Sie die Standard-API-Rate-Limits für verschiedene Anfragetypen. Diese Standardlimits können auf Anfrage erhöht werden. Kontaktieren Sie Ihren Customer-Success-Manager für weitere Informationen.
Anfragen mit unterschiedlichen Rate-Limits
| Anfragetyp | Standard-API-Rate-Limit |
|---|---|
/users/track |
Anfragen: 3.000 Anfragen pro drei Sekunden. Batching: Bis zu 75 Objekte insgesamt, kombiniert aus 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 monatlich aktive Nutzer:innen CY 24-25, Universal MAU, Web MAU und Mobile MAU: Bitte beachten Sie die Hinweise zu den Limits hier. |
/users/export/ids |
Wenn Sie am oder nach dem 22. August 2024 das Onboarding durchlaufen haben: 250 Anfragen pro Minute. Wenn Sie vor dem 22. August 2024 das Onboarding durchlaufen haben: 2.500 Anfragen pro Minute. |
/users/delete/users/alias/new/users/alias/update/users/identify/users/merge |
20.000 Anfragen pro Minute, aufgeteilt auf die 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 (bei breitem Targeting auf Segmente, Filter oder eine verbundene 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 wird die Anfrage beim Targeting einzelner Empfänger:innen in das gemeinsame 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, gemeinsam genutzt von den Endpunkten. |
/catalogs/{catalog_name}/items/catalogs/{catalog_name}/items/catalogs/{catalog_name}/items |
16.000 Anfragen pro Minute, aufgeteilt auf die 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 genutzt von 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, gemeinsam genutzt von den Endpunkten. |
/scim/v2/Users/{id}/scim/v2/Users?filter={[email protected]}/scim/v2/Users/{id}/scim/v2/Users/{id}}/scim/v2/Users/ |
5.000 Anfragen pro Tag, pro Unternehmen, aufgeteilt auf die 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—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 gilt 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 wird davon ausgegangen, dass Broadcast-Anfragen dieselbe eindeutige Zielgruppe ansprechen, wenn alle folgenden Kriterien übereinstimmen:
- Die Campaign oder das Canvas, die/das getriggert wird (die
campaign_idodercanvas_idin Ihrer API-Anfrage, falls angegeben) - Die angesprochene Zielgruppe (die Segmente oder Filter oder, bei API-Kampagnen, die
segment_idin Ihrer API-Anfrage) - Die verbundenen Zielgruppen-Filter (das
audience-Objekt in Ihrer API-Anfrage, falls angegeben)
Jede eindeutige Kombination dieser Attribute wird als eigenständige Zielgruppe betrachtet, sodass das zusätzliche Rate-Limit für jede eindeutige Zielgruppe unabhängig für jede Kombination gilt.
Batching von API-Anfragen
Braze APIs unterstützen Batching. Mit Batching kann Braze so viele Daten wie möglich in einem einzigen API-Aufruf aufnehmen, sodass Sie nicht viele einzelne API-Aufrufe tätigen müssen. Für Braze ist es effizienter, Daten in Stapeln zu verarbeiten als einzeln pro Aufruf. Die Verarbeitung von 1.000 gebündelten API-Aufrufen erfordert zum Beispiel weniger Ressourcen als die Verarbeitung von 75.000 einzelnen Aufrufen. Batching ist besonders wichtig für Anwendungen, die möglicherweise mehr als 75.000 Aufrufe pro Stunde benötigen.
Erhöhungen der REST API Rate-Limits werden bedarfsabhängig für Kund:innen in Betracht gezogen, die die API-Batching-Funktionen nutzen.
Batching von Anfragen für den Endpunkt „Nutzer:innen tracken“
Jede /users/track-Anfrage kann bis zu 75 Objekte insgesamt enthalten, kombiniert aus 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) bis zu 75 Objekte unabhängig voneinander enthalten, was ein kombiniertes Maximum von bis zu 225 Objekten 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 dieser Reihenfolge verarbeitet:
- Attribute
- Events
- Käufe
Batching von Messaging-Endpunkt-Anfragen
Eine einzelne Anfrage an die Messaging-Endpunkte kann Folgendes umfassen:
- Bis zu 50 spezifische
external_ids, jeweils mit individuellen Nachrichtenparametern - Ein im Braze-Dashboard erstelltes Segment beliebiger Größe, angegeben durch seine
segment_id - Nutzer:innen, die zusätzlichen Zielgruppen-Filtern beliebiger Größe entsprechen, die in der Anfrage als verbundenes Zielgruppen-Objekt definiert sind
Beispiel einer Batch-Anfrage
Das folgende Beispiel verwendet external_id, um einen API-Aufruf für E-Mail und SMS zu tätigen.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
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 gibt die folgenden Informationen in den Antwort-Headern zurück:
| Header-Name | Beschreibung |
|---|---|
X-RateLimit-Limit |
Die maximale Anzahl der 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. |
Diese Informationen sind bewusst im Header der API-Antwort enthalten und nicht im Braze-Dashboard. So kann Ihr System in Echtzeit reagieren, während Sie mit unserer API interagieren. Wenn zum Beispiel der Wert von X-RateLimit-Remaining unter einen bestimmten Schwellenwert fällt, sollten Sie den Versand verlangsamen, um sicherzustellen, dass alle Transaktions-E-Mails zugestellt werden. Oder wenn der Wert Null erreicht, können Sie alle Sendungen pausieren, bis die in X-RateLimit-Reset angegebene Zeit abgelaufen ist.
HTTP-Header werden ausschließlich in Kleinbuchstaben zurückgegeben. Dieses Verhalten entspricht dem HTTP/2-Protokoll, das vorschreibt, dass alle Header-Feldnamen kleingeschrieben werden müssen. Dies unterscheidet sich von HTTP/1.X, wo Header-Namen nicht zwischen Groß- und Kleinschreibung unterschieden, aber üblicherweise in verschiedenen Schreibweisen verwendet 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 Dashboard zur API-Nutzung verwenden, um den eingehenden Datenverkehr im Vergleich zu Ihren Rate-Limits anzuzeigen und zu 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 entscheidend, wenn Sie aufeinanderfolgende Aufrufe an die Braze API senden. Probleme entstehen, wenn Endpunkte von der erfolgreichen Verarbeitung anderer Endpunkte abhängen und bei einem zu frühen Aufruf Fehler auftreten können. Wenn Sie zum Beispiel Nutzer:innen über den Endpunkt /user/alias/new einen Alias zuweisen und diesen Alias anschließend verwenden, um über den Endpunkt /users/track ein angepasstes Event zu senden – wie lange sollten Sie dann warten?
Unter normalen Bedingungen beträgt die Zeit bis zur eventualen Datenkonsistenz 10–100 ms (1/10 Sekunde). Es kann jedoch vorkommen, dass es länger dauert, bis diese Konsistenz eintritt. Daher empfehlen wir, zwischen aufeinanderfolgenden Aufrufen eine Verzögerung von 5 Minuten einzuplanen, um die Fehlerwahrscheinlichkeit zu minimieren.
Limits für die Payload-Größe
Braze API-Anfragen unterliegen Limits für die Payload-Größe, die unabhängig von den Rate-Limits gelten. Die meisten Endpunkte akzeptieren Anfragekörper von bis zu 4 MB. Wenn eine Anfrage das geltende Limit überschreitet, kann Braze sie je nach Endpunkt mit HTTP 413 Request Entity Too Large oder HTTP 400 Bad Request ablehnen.
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 Fenster. 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 stellen, da der Zähler zu jeder vollen Stunde zurückgesetzt wird.