Webhookとコネクテッドコンテンツリクエストのトラブルシューティング

このページでは、Webhookとコネクテッドコンテンツの一般的なエラーコードのトラブルシューティング方法について説明します。設定については、Webhookの作成とAPI呼び出しの実行を参照してください。

まずはここから：症状を照合する

以下の表で症状を照合し、該当するセクションに移動してください。

症状	移動先
メッセージアクティビティログに 4XX クライアントエラーが表示される	4XXエラー
5XX サーバーエラーまたはタイムアウト	5XXエラー
598 Host Unhealthy またはリクエストが一時的に停止される	異常ホスト検出
コネクテッドコンテンツがプレビューまたは送信で空白として表示される	コネクテッドコンテンツがレスポンスボディを返さない場合
Brazeからの自動エラーメール	自動メールとメッセージアクティビティログのエントリ
Currentsでwebhookの失敗イベントが必要	Braze Currentsでの追加の失敗インサイト

標準的な調査パス

Webhookまたはコネクテッドコンテンツリクエストが失敗したり、正しくレンダリングされない場合は、このワークフローを使用してください。ステップ1から開始します。

1. メッセージアクティビティログを開き、エラーコード、タイムスタンプ、エンドポイントURLを確認します。
2. 4XX エラーの場合は、エンドポイントのドキュメントに照らして、リクエスト構文、認証ヘッダー、URLパス、HTTPメソッドを確認します。
3. 5XX エラーの場合は、エンドポイントの正常性、レート制限、およびBrazeがホストを異常としてフラグ付けしたかどうかを確認します。
4. コネクテッドコンテンツの場合は、テストユーザーでメッセージをプレビューし、Liquidが空白やJSONを壊す値に解決されていないことを確認します。
5. 異常ホスト検出が関係している可能性がある場合は、Brazeサポートに連絡する前に異常ホスト検出を確認してください。

4XXエラー {#4xx-errors} {#4xx-errors}

4XX エラーは、エンドポイントに送信されたリクエストに問題があることを示します。これらのエラーは通常、不正なパラメーター、認証ヘッダーの欠落、不正なURLなど、誤ったリクエストが原因で発生します。これらのエラーはレポートビルダーにも適用されることに注意してください。

エラーコードの詳細と解決手順については、以下の表を参照してください。

エラーコード	意味	解決手順
400 Bad Request	リクエストに無効な構文があります。	リクエストペイロードに構文エラーがないか確認してください。 すべての必須フィールドが含まれ、正しくフォーマットされていることを確認してください。 JSONペイロードを送信している場合は、JSON構造を検証してください。 Liquidを使用してWebhookリクエストにパーソナライゼーションタグをテンプレート化している場合は、Liquidが空白の値に解決されたり、JSONを壊す文字（エスケープされていない引用符など）を生成したりしないことを確認してください。テストユーザーでメッセージをプレビューして、レンダリングされた出力が有効であることを確認してください。
401 Unauthorized	リクエストにはユーザー認証が必要です。	正しい認証情報（APIキーやトークンなど）がリクエストヘッダーに含まれていることを確認してください。 エンドポイントにアクセスするためのユーザー権限があることを確認してください。
403 Forbidden	エンドポイントはリクエストを理解しましたが、認可を拒否しました。	APIキーまたはトークンに必要な権限があるか確認してください。 エンドポイントにアクセスするためのユーザー権限があることを確認してください。
404 Not Found	エンドポイントがリクエストされたリソースを見つけられません。	エンドポイントURLにタイプミスや不正なパスがないか確認してください。 アクセスしようとしているリソースが存在することを確認してください。
405 Method Not Allowed	リクエストメソッドはエンドポイントに認識されていますが、ターゲットリソースではサポートされていません。	リクエストで使用されているHTTPメソッド（DELETE、GET、POST、PUT）を確認してください。 エンドポイントが使用しているメソッドをサポートしていることを確認してください。
408 Request Timeout	エンドポイントがリクエストの処理中にタイムアウトしました。	リクエストで使用されているHTTPメソッド（DELETE、GET、POST、PUT）を確認してください。 エンドポイントが使用しているメソッドをサポートしていることを確認してください。
409 Conflict	リソースの現在の状態との競合により、リクエストが不完全です。	リクエストで使用されているHTTPメソッド（DELETE、GET、POST、PUT）を確認してください。 エンドポイントが使用しているメソッドをサポートしていることを確認してください。
429 Too Many Requests	一定時間内に送信されたリクエストが多すぎます。	キャンペーンまたはキャンバスステップのレート制限を下げてください。

5XXエラー {#5xx-errors} {#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とコネクテッドコンテンツは、ターゲットホストが高い割合で著しい遅延や過負荷を経験し、タイムアウト、リクエスト過多、またはBrazeがターゲットエンドポイントと正常に通信できないその他の結果が生じている場合に検出する異常ホスト検出メカニズムを採用しています。これは、ターゲットホストの問題の原因となっている可能性のある不要な負荷を軽減するためのセーフガードとして機能します。また、Brazeインフラの安定化と高速なメッセージング速度の維持にも役立ちます。

検出しきい値はWebhookとコネクテッドコンテンツで異なります。

• Webhookの場合: 1分間の移動時間枠内で失敗が3,000件を超えた場合（ホスト名とアプリグループのユニークな組み合わせごと—エンドポイントパスごとではありません）、Brazeはターゲットホストへのリクエストを1分間一時的に停止します。
• コネクテッドコンテンツの場合: 1分間の移動時間枠内で失敗が3,000件を超え、かつエラー率が90%を超えた場合（ホスト名とアプリグループのユニークな組み合わせごと—エンドポイントパスごとではありません）、Brazeはターゲットホストへのリクエストを1分間一時的に停止します。

リクエストが停止されると、Brazeは 598 エラーコードで応答をシミュレートし、異常な状態を示します。1分後、ホストが正常であることが確認された場合、Brazeはフルスピードでリクエストを再開します。ホストがまだ異常な場合、Brazeは再試行する前にさらに1分間待機します。

以下のエラーコードが異常ホスト検出の失敗カウントに寄与します: 408、429、502、503、504、529。

Webhookの場合、Brazeは異常ホスト検出によって停止されたHTTPリクエストを自動的にリトライします。この自動リトライはエクスポネンシャルバックオフを使用し、失敗するまで数回のみリトライします。Webhookエラーの詳細については、エラー、リトライロジック、タイムアウトを参照してください。

コネクテッドコンテンツの場合、ターゲットホストへのリクエストが異常ホスト検出によって停止されると、Brazeはエラー応答コードを受信したかのようにメッセージのレンダリングを続行し、Liquidロジックに従います。これらのコネクテッドコンテンツリクエストが異常ホスト検出によって停止された際にリトライされるようにするには、:retry オプションを使用してください。:retry オプションの詳細については、コネクテッドコンテンツのリトライを参照してください。

異常ホスト検出が問題を引き起こしていると思われる場合は、Brazeサポートにお問い合わせください。

コネクテッドコンテンツがレスポンスボディを返さない場合

症状: コネクテッドコンテンツの呼び出しがメッセージプレビューまたは送信で空白として表示されます。

コネクテッドコンテンツの呼び出しがメッセージプレビューまたは送信で空白として表示される場合は、以下を確認してください。

• URL内のノーブレークスペース: Brazeはリクエストを行う前に、コネクテッドコンテンツURLからノーブレークスペース（  またはUnicode U+00A0）を除去します。URLがドキュメントやダッシュボードのフィールドからコピーされ、文字間にノーブレークスペースが挿入されていた場合、リクエストが失敗するか、使用可能なボディが返されない可能性があります。URLをプレーンテキストで再入力するか、隠れたスペースを削除してから、再度プレビューしてください。
• HTTPエラーと空のボディ: ステータスコード300以上やホストがブロックされている場合、コネクテッドコンテンツは空の文字列をレンダリングすることがあります。API呼び出しの実行を参照し、メッセージアクティビティログで失敗を確認してください。

自動メールとメッセージアクティビティログのエントリ

自動メールの設定

ワークスペースで24時間以内にWebhookまたはコネクテッドコンテンツのエンドポイントエラー（リトライを含む）が100,000件を超えた場合、Brazeはエラーの解決方法に関する以下の情報を含むメールを送信します。

• ワークスペース名
• キャンバスまたはキャンペーンへのリンク
• エンドポイントURL
• エラーコード
• エラーが最後に観測された時刻
• メッセージアクティビティログおよび関連ドキュメントへのリンク

エンドポイントエラーは以下のとおりです。

• 4XX: 400、401、403、404、405、408、409、429
• 5XX: 500、502、503、504、598、599

これらのメールはワークスペースレベルで1日1回のみ送信されます。これらのメールに登録しているユーザーがいない場合、Brazeはすべての会社管理者に通知します。

これらのメールを受信するには、以下の手順を実行してください。

1. 設定 > 管理者設定 > 通知設定に移動します。
2. キャンバスとキャンペーンセクションでConnected Content ErrorsとWebhook Errorsを選択します。

メッセージアクティビティログのエントリ

失敗が発生した場合、メッセージアクティビティログに関連するエントリが少なくとも1つあります。リクエストがリトライされて最終的に成功した場合、その詳細はCurrentsとSnowflakeデータ共有で確認できます。リトライ後にリクエストが最終的に成功した場合でも、エラーは自動メールをトリガーする可能性があることに注意してください。

Braze Currentsでの追加の失敗インサイト

Webhook関連の問題に対する透明性を高めるため、BrazeはWebhookの失敗イベントの詳細をCurrentsとSnowflakeデータ共有にストリーミングします。これらのイベントには、失敗したWebhookリクエスト（HTTP 4xx または 5xx 応答など）が含まれ、Webhookの問題がメッセージ配信にどのように影響するかについてより高い可観測性を提供します。失敗イベントには、最終的なエラーとリトライ中のエラーの両方が含まれることに注意してください。

詳細については、メッセージエンゲージメントイベント用語集を参照してください。