Webhookとコネクテッドコンテンツリクエストのトラブルシューティング
このページでは、webhookとコネクテッドコンテンツの一般的なエラーコードのトラブルシューティング方法について説明します。設定については、Webhookの作成とAPI呼び出しの実行を参照してください。プレビューでConnected Contentリクエストを確認するには、Connected Contentデバッガーを参照してください。
ここから始める：症状を照合する
以下の表から症状を照合して、関連するセクションに移動してください。
| 症状 | 移動先 |
|---|---|
メッセージアクティビティログで 4XX クライアントエラー |
4XX エラー |
5XX サーバーエラーまたはタイムアウト |
5XX エラー |
598 Host Unhealthy またはリクエストが一時的に停止 |
異常ホストの検出 |
| Connected Contentがプレビューまたは送信時に空白で表示される | Connected Contentがレスポンスボディを返さない |
| プレビューでConnected Contentリクエストを検査する必要がある | Connected Content デバッガー |
| Brazeからの自動エラーメール | 自動メールとメッセージアクティビティログのエントリ |
| CurrentsでWebhook失敗イベントが必要 | Braze Currentsでの追加の失敗インサイト |
標準的な調査パス
Webhookまたは Connected Contentリクエストが失敗した場合や正しくレンダリングされない場合は、このワークフローを使用してください。ステップ1から開始します。
- メッセージアクティビティログを開き、エラーコード、タイムスタンプ、エンドポイントURLを確認します。
4XXエラーの場合は、エンドポイントのドキュメントに照らしてリクエスト構文、認証ヘッダー、URLパス、HTTPメソッドを検証します。5XXエラーの場合は、エンドポイントの稼働状態、レート制限、およびBrazeがそのホストを異常と判定したかどうかを確認します。- Connected Contentの場合は、テストユーザーでメッセージをプレビューします。Connected Contentデバッガーを使用してリクエストとレスポンスを検査し、Liquidが空白やJSON構文を壊す値に解決されていないことを確認します。
- 異常ホスト検出が関係している可能性がある場合は、Brazeサポートに問い合わせる前に異常ホスト検出を確認してください。
4XX エラー {#4xx-errors}
4XX エラーは、エンドポイントに送信されたリクエストに問題があることを示します。これらのエラーは通常、不正なパラメーター、認証ヘッダーの欠落、不正な URL など、誤ったリクエストが原因で発生します。これらのエラーはレポートビルダーにも適用されます。
エラーコードの詳細と解決手順については、以下の表を参照してください。
| エラーコード | 意味 | 解決手順 |
|---|---|---|
| 400 Bad Request | リクエストに無効な構文があります。 |
|
| 401 Unauthorized | リクエストにはユーザー認証が必要です。 |
|
| 403 Forbidden | エンドポイントはリクエストを理解していますが、承認を拒否しています。 |
|
| 404 Not Found | エンドポイントがリクエストされたリソースを見つけられません。 |
|
| 405 Method Not Allowed | リクエストメソッドはエンドポイントに認識されていますが、対象リソースではサポートされていません。 |
|
| 408 Request Timeout | エンドポイントがリクエストの処理中にタイムアウトしました。 |
|
| 409 Conflict | リソースの現在の状態との競合のため、リクエストが完了できません。 |
|
| 429 Too Many Requests | 一定時間内に送信されたリクエストが多すぎます。 |
|
5XXエラー {#5xx-errors}
5XXエラーは、エンドポイントに問題があることを示します。これらのエラーは通常、サーバー側の問題が原因で発生します。
| エラーコード | 意味 |
|---|---|
| 500 Internal Server Error | エンドポイントがリクエストの完了を妨げる予期しない状態に遭遇しました。 |
| 502 Bad Gateway | エンドポイントが上流サーバーから無効なレスポンスを受信しました。 |
| 503 Service Unavailable | エンドポイントは、一時的な過負荷またはメンテナンスのため、現在リクエストを処理できません。 |
| 504 Gateway Timeout | エンドポイントが上流サーバーからタイムリーなレスポンスを受信できませんでした。 |
| 529 Host Overloaded | エンドポイントのホストが過負荷状態で、レスポンスを返せませんでした。 |
| 598 Host Unhealthy | エンドポイントのホストが一時的に異常としてマークされているため、Brazeがレスポンスをシミュレートしました。詳細については、異常なホストの検出を参照してください。 |
| 599 Connection Error | Brazeがエンドポイントへの接続を確立しようとした際にネットワーク接続タイムアウトエラーが発生しました。エンドポイントが不安定またはダウンしている可能性があります。 |
5XXエラーの解決
一般的な5XXエラーのトラブルシューティングに役立つヒントを紹介します。
- メッセージアクティビティログで利用可能な具体的な詳細について、エラーメッセージを確認してください。webhookの場合は、Brazeホームページの経時パフォーマンスセクションに移動し、webhookの統計を選択してください。ここから、エラーが発生したタイムスタンプを確認できます。
- エンドポイントに過負荷をかけるほど多くのリクエストを送信していないか確認してください。バッチで送信するか、レート制限を調整して、エラーが減少するか確認できます。
異常ホスト検出
BrazeのWebhookとConnected Contentは、ターゲットホストが高い割合で著しい遅延や過負荷を経験し、タイムアウト、リクエスト過多、またはBrazeがターゲットエンドポイントと正常に通信できないその他の結果が生じている場合に検出する異常ホスト検出メカニズムを採用しています。これは、ターゲットホストの問題の原因となっている可能性のある不要な負荷を軽減するためのセーフガードとして機能します。また、Brazeインフラの安定化と高速なメッセージング速度の維持にも役立ちます。
検出しきい値はWebhookとConnected Contentで異なります。
- Webhookの場合: 1分間の移動時間枠内で失敗が3,000件を超えた場合（ホスト名とアプリグループのユニークな組み合わせごと—エンドポイントパスごとではありません）、Brazeはターゲットホストへのリクエストを1分間一時的に停止します。
- Connected Contentの場合: 1分間の移動時間枠内で失敗が3,000件を超え、かつエラー率が90%を超えた場合（ホスト名とアプリグループのユニークな組み合わせごと—エンドポイントパスごとではありません）、Brazeはターゲットホストへのリクエストを1分間一時的に停止します。
リクエストが停止されると、Brazeは598エラーコードで応答をシミュレートし、異常な状態を示します。1分後、ホストが正常であることが確認された場合、Brazeはフルスピードでリクエストを再開します。ホストがまだ異常な場合、Brazeは再試行する前にさらに1分間待機します。
以下のエラーコードが異常ホスト検出の失敗カウントに寄与します: 408、429、502、503、504、529。
Webhookの場合、Brazeは異常ホスト検出によって停止されたHTTPリクエストを自動的にリトライします。この自動リトライはエクスポネンシャルバックオフを使用し、失敗するまで数回のみリトライします。Webhookエラーの詳細については、エラー、リトライロジック、タイムアウトを参照してください。
Connected Contentの場合、ターゲットホストへのリクエストが異常ホスト検出によって停止されると、Brazeはエラー応答コードを受信したかのようにメッセージのレンダリングを続行し、Liquidロジックに従います。これらのConnected Contentリクエストが異常ホスト検出によって停止された際にリトライされるようにするには、:retryオプションを使用してください。:retryオプションの詳細については、Connected Contentのリトライを参照してください。
異常ホスト検出が問題を引き起こしていると思われる場合は、Brazeサポートにお問い合わせください。
Connected Contentがレスポンスボディを返さない場合
症状: Connected Contentの呼び出しがメッセージプレビューまたは送信で空白として表示されます。
Connected Contentの呼び出しがメッセージプレビューまたは送信で空白として表示される場合は、Connected Contentデバッガーを使用してリクエストとレスポンスを検査し、以下を確認してください。
- URL内のノーブレークスペース: Brazeはリクエストを行う前に、Connected ContentのURLからノーブレークスペース（
またはUnicodeU+00A0）を除去します。URLがドキュメントやダッシュボードのフィールドからコピーされ、文字間にノーブレークスペースが挿入されていた場合、リクエストが失敗するか、使用可能なボディが返されない可能性があります。URLをプレーンテキストで再入力するか、隠れたスペースを削除してから、再度プレビューしてください。 - リダイレクト応答（
3xx）: Connected Contentはリダイレクトに従いません。2xx応答のみが成功として扱われるため、301や302は同じURLがPostmanで動作する場合でも空白として表示されることがあります。最終的なリダイレクト先URLを使用するか、Brazeが呼び出すURLで2xx応答（通常は200）を返すようにエンドポイントを設定してください。エンドポイントがリダイレクトを返す場合にConnected Contentが失敗するのはなぜですか？を参照してください。 - HTTPエラーと空のボディ:
2xx範囲外のステータスコードやブロックされたホストの場合、Connected Contentは空の文字列をレンダリングすることがあります。API呼び出しの実行を参照し、メッセージアクティビティログで失敗を確認してください。
自動メールとメッセージアクティビティログのエントリ
自動メールの設定
ワークスペースで24時間以内にWebhookまたはコネクテッドコンテンツのエンドポイントエラー（リトライを含む）が100,000件を超えた場合、Brazeはエラーの解決方法に関する以下の情報を含むメールを送信します。
- ワークスペース名
- キャンバスまたはキャンペーンへのリンク
- エンドポイントURL
- エラーコード
- エラーが最後に観測された時刻
- メッセージアクティビティログおよび関連ドキュメントへのリンク
エンドポイントエラーは以下のとおりです。
4XX:400、401、403、404、405、408、409、4295XX:500、502、503、504、598、599
これらのメールはワークスペースレベルで1日1回のみ送信されます。これらのメールに登録しているユーザーがいない場合、Brazeはすべての会社管理者に通知します。
これらのメールを受信するには、以下の手順を実行してください。
- 設定 > 管理者設定 > 通知設定に移動します。
- キャンバスとキャンペーンセクションでConnected Content ErrorsとWebhook Errorsを選択します。
メッセージアクティビティログのエントリ
失敗が発生した場合、メッセージアクティビティログに関連するエントリが少なくとも1つあります。リクエストがリトライされて最終的に成功した場合、その詳細はCurrentsとSnowflakeデータ共有で確認できます。リトライ後にリクエストが最終的に成功した場合でも、エラーは自動メールをトリガーする可能性があることに注意してください。
Braze Currentsでの追加の失敗インサイト
Webhook関連の問題に対する透明性を高めるため、BrazeはWebhookの失敗イベントの詳細をCurrentsとSnowflakeデータ共有にストリーミングします。これらのイベントには、失敗したWebhookリクエスト（HTTP 4xx または 5xx 応答など）が含まれ、Webhookの問題がメッセージ配信にどのように影響するかについてより高い可観測性を提供します。失敗イベントには、最終的なエラーとリトライ中のエラーの両方が含まれることに注意してください。
コネクテッドコンテンツリクエストは、これらのWebhook失敗イベントには含まれません。
詳細については、メッセージエンゲージメントイベント用語集を参照してください。