レート制限
BrazeのAPIインフラは、顧客ベース全体で大量のデータを処理できるように設計されています。このため、ワークスペースごとにAPIレート制限を設けています。
レート制限とは、APIが一定時間内に受け取れるリクエスト数のことです。大規模システムにおける負荷ベースのサービス拒否インシデントの多くは、悪意のある攻撃ではなく、ソフトウェアや設定のエラーによって引き起こされる意図しないものです。レート制限は、このようなエラーによってBraze APIのリソースがお客様に提供できなくなることを防ぎます。一定時間内に多くのリクエストが送信された場合、ステータスコード429のエラー応答が返されることがあります。これは、レート制限に達したことを示します。
APIレート制限は、システムの適切な使用状況に応じて変更される場合があります。損害や悪用を防ぐため、APIコールを行う際には適切な制限を設けることを推奨します。
リクエストタイプ別のレート制限
さまざまなリクエストタイプのデフォルトの API レート制限については、以下を参照してください。これらのデフォルト制限は、リクエストに応じて引き上げることができます。詳細については、カスタマーサクセスマネージャーにお問い合わせください。
異なるレート制限を持つリクエスト
共有レート制限を持つリクエスト
以下のリクエストには、1 時間あたり 250,000 リクエストのレート制限があり、これらのリクエスト間で共有されます。
/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(非ブロードキャスト呼び出し、つまりexternal_user_idsまたはaliasesを指定する呼び出しのみ)/campaigns/trigger/schedule/create(非ブロードキャスト呼び出しのみ)/campaigns/trigger/schedule/delete/campaigns/trigger/schedule/update/canvas/data_series/canvas/data_summary/canvas/details/canvas/list/canvas/trigger/send(非ブロードキャスト呼び出しのみ)/canvas/trigger/schedule/create(非ブロードキャスト呼び出しのみ)/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(非ブロードキャスト呼び出しのみ)/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
同じユニークオーディエンスとみなされる条件
これは次のエンドポイントに適用されます: /messages/send、/campaigns/trigger/send、/canvas/trigger/send、/campaigns/trigger/schedule/create、/canvas/trigger/schedule/create。
これらのエンドポイントでは、以下のすべてが一致する場合に、ブロードキャストリクエストが同じユニークオーディエンスを対象としているとみなされます。
- トリガーされるキャンペーンまたはキャンバス (指定されている場合は、API リクエスト内の
campaign_idまたはcanvas_id) - 対象となるオーディエンス (セグメントまたはフィルター、API キャンペーンの場合は API リクエスト内の
segment_id) - 接続オーディエンスフィルター (指定されている場合は、API リクエスト内の
audienceオブジェクト)
これらの属性の一意の組み合わせはそれぞれ別個のオーディエンスとしてカウントされるため、ユニークオーディエンスごとの追加レート制限は、各組み合わせに個別に適用されます。
API リクエストのバッチ処理
Braze API はバッチ処理に対応しています。バッチ処理を使うと、1 回の API 呼び出しでできるだけ多くのデータを Braze に送信できるため、API 呼び出しの回数を減らせます。Braze にとっても、1 回ずつデータを処理するよりバッチでまとめて処理するほうが効率的です。たとえば、1,000 件のバッチ API 呼び出しの処理に必要なリソースは、75,000 件の個別呼び出しの処理よりも少なくて済みます。1 時間あたり 75,000 件を超える呼び出しが必要になる可能性があるアプリケーションでは、バッチ処理が非常に重要です。
REST APIのレート制限の引き上げは、API のバッチ処理機能を活用している顧客を対象に、必要性に応じて検討されます。
ユーザーの作成と更新エンドポイントへのリクエストのバッチ処理
各 /users/track リクエストには、attributes、events、purchases を合わせて最大 75 個のオブジェクトを含めることができます。各オブジェクトで 1 人のユーザーを更新できます。1 つのユーザープロファイルを複数のオブジェクトで更新することもできます。
従来のレート制限
従来のレート制限が適用されている顧客の場合、各配列 (attributes、events、purchases) にそれぞれ最大 75 個のオブジェクトを含めることができ、1 リクエストあたり合計で最大 225 個のオブジェクトを送信できます。
/users/track のレート制限の詳細については、POST:ユーザーの作成と更新を参照してください。
このエンドポイントへのリクエストは、通常、次の順序で処理が開始されます。
- 属性
- イベント
- 購入
メッセージングエンドポイントへのリクエストのバッチ処理
メッセージングエンドポイントへの 1 回のリクエストで、次のいずれかに送信できます。
- 最大 50 件の特定の
external_ids(それぞれに個別のメッセージパラメーターを指定可能) - Braze ダッシュボードで作成された任意のサイズのセグメント (
segment_idで指定) - リクエスト内で接続オーディエンスオブジェクトとして定義された、任意のサイズの追加オーディエンスフィルターに一致するユーザー
バッチリクエストの例
次の例では、external_id を使用して、メールと SMS の両方を対象に 1 回の API 呼び出しを行います。
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]"]
}
]
}
レート制限のモニタリング
標準の REST API レート制限の対象となる Braze への API リクエストでは、すべてレスポンスヘッダーで次の情報が返されます。
| ヘッダー名 | 説明 |
|---|---|
X-RateLimit-Limit |
指定された間隔内に送信できるリクエストの最大数 (レート制限)。 |
X-RateLimit-Remaining |
現在のレート制限ウィンドウ内で残っているリクエスト数。 |
X-RateLimit-Reset |
現在のレート制限ウィンドウがリセットされる時刻 (UTC エポック秒)。 |
トランザクションメールエンドポイントなど、標準の REST API レート制限を回避するエンドポイントは、外部 API レート制限全体にはカウントされず、これらのヘッダーも返されません。
この情報は、Braze ダッシュボードではなく、API リクエストに対するレスポンスのヘッダーに意図的に含まれています。これにより、API とやり取りする際に、システムがリアルタイムでより適切に対応できます。たとえば、X-RateLimit-Remaining の値が特定のしきい値を下回った場合は、リクエストのペースを落とすことができます。また、値がゼロになった場合は、X-RateLimit-Reset で指定された時刻が経過するまでリクエストを一時停止することもできます。
429 Too Many Requests レスポンスのトラブルシューティング
連携がレート制限を超えたためにエンドポイントが HTTP 429 Too Many Requests レスポンスを返した場合は、レスポンスヘッダーを使用して再試行のタイミングを判断します。
- リクエストを一時停止します。レスポンスに
X-RateLimit-Retry-Afterが含まれている場合は、指定された秒数だけ待機します。含まれていない場合は、X-RateLimit-Resetの UTC エポックタイムスタンプまで待機します。 - より低いレートでリクエストを再開します。各レート制限ウィンドウ内で送信するリクエスト数を減らし、再び
429レスポンスが返される可能性を下げます。 - サポートされている場合は、複数の更新を 1 つのリクエストにまとめます。
/users/trackについては、アカウントのリクエストオブジェクト制限に従ってください。 - API 使用状況ダッシュボードを使用して、リクエストの急増や
429レスポンスの傾向を特定します。
エンドポイント固有のデフォルトについては、リクエストタイプ別のレート制限を参照してください。
429 Too Many Requests レスポンスのトラブルシューティング
連携がレート制限を超えたためにエンドポイントが HTTP 429 Too Many Requests レスポンスを返した場合は、レスポンスヘッダーを使用して再試行のタイミングを判断します。
- リクエストを一時停止します。レスポンスに
X-RateLimit-Retry-Afterが含まれている場合は、指定された秒数だけ待機します。含まれていない場合は、X-RateLimit-Resetの UTC エポックタイムスタンプまで待機します。 - より低いレートでリクエストを再開します。各レート制限ウィンドウ内で送信するリクエスト数を減らし、再び
429レスポンスが返される可能性を下げます。 - サポートされている場合は、複数の更新を 1 つのリクエストにまとめます。
/users/trackについては、アカウントのリクエストオブジェクト制限に従ってください。 - API 使用状況ダッシュボードを使用して、リクエストの急増や
429レスポンスの傾向を特定します。
エンドポイント固有のデフォルトについては、リクエストタイプ別のレート制限を参照してください。
HTTP ヘッダーはすべて小文字で返されます。この動作は、すべてのヘッダーフィールド名を小文字にすることを義務付けている HTTP/2 プロトコルに準拠したものです。これは、ヘッダー名で大文字と小文字が区別されず、さまざまな大文字・小文字の表記で書かれることが一般的だった HTTP/1.X とは異なります。
API の制限についてご質問がある場合は、カスタマーサクセスマネージャーに問い合わせるか、サポートチケットを作成してください。
エンドポイント間の最適な遅延
エラーを最小限に抑えるため、連続するエンドポイント呼び出しの間に 5 分の遅延を設けることをおすすめします。
Braze API を連続して呼び出す場合、エンドポイント間の最適な遅延を理解することが非常に重要です。あるエンドポイントが他のエンドポイントの正常な処理に依存している場合、呼び出しが早すぎるとエラーが発生する可能性があります。たとえば、/user/alias/new エンドポイントを通じてユーザーにエイリアスを割り当て、そのエイリアスを使用して /users/track エンドポイントからカスタムイベントを送信する場合、どのくらい待つべきでしょうか。
通常の状況では、データの結果整合性が確保されるまでの時間は 10～100 ミリ秒 (1/10 秒) です。ただし、整合性の確保にそれ以上の時間がかかる場合もあるため、エラーの可能性を最小限に抑えるために、後続の呼び出しを行う間に 5 分の遅延を設けることをおすすめします。
ペイロードサイズの制限
Braze APIリクエストには、レート制限とは別にペイロードサイズの制限があります。ほとんどのエンドポイントでは、最大4 MBのリクエスト本文を受け付けます。リクエストが該当する制限を超えると、エンドポイントに応じて、Brazeは HTTP 413 Request Entity Too Large または HTTP 400 Bad Request でリクエストを拒否する場合があります。
/users/track/bulk エンドポイントのペイロード制限は2 MBで、リクエスト本文がこの制限を超えると HTTP 400 を返します。エンドポイント固有の制限とエラー処理については、ユーザーデータエンドポイントを参照してください。
レート制限のリセット
レート制限は、ローリングウィンドウではなく、毎時0分にリセットされます。たとえば、制限が1時間あたり250,000リクエストの場合、カウンターは毎時0分にリセットされるため、午後10:00から午後10:59の間に50,000リクエストを送信し、午後11:00から午後11:59の間にさらに250,000リクエストを送信できます。