Webhookとコネクテッドコンテンツリクエストのトラブルシューティング
このページでは、Webhookとコネクテッドコンテンツの一般的なエラーコードのトラブルシューティング方法について説明します。設定については、Webhookの作成とAPI呼び出しの実行を参照してください。
ここから始めましょう：症状を確認する
以下の表で症状を確認し、該当するセクションに移動してください。
| 症状 | 移動先 |
|---|---|
メッセージアクティビティログの 4XX クライアントエラー |
4XX エラー |
5XX サーバーエラーまたはタイムアウト |
5XX エラー |
598 Host Unhealthy またはリクエストの一時停止 |
異常なホストの検出 |
| Connected Contentがプレビューまたは送信時に空白で表示される | Connected Contentがレスポンスボディを返さない |
| Brazeからの自動エラーメール | 自動メールとメッセージアクティビティログのエントリ |
| Currentsでwebhookの失敗イベントが必要 | Braze Currentsでの追加の失敗インサイト |
標準的な調査パス
Webhookまたは Connected Content リクエストが失敗したり、正しくレンダリングされない場合は、このワークフローを使用してください。ステップ1から開始します。
- メッセージアクティビティログを開き、エラーコード、タイムスタンプ、エンドポイントURLを確認します。
4XXエラーの場合、エンドポイントのドキュメントと照らし合わせて、リクエスト構文、認証ヘッダー、URLパス、HTTPメソッドを確認します。5XXエラーの場合、エンドポイントの稼働状況、レート制限、およびBrazeがホストを異常と判定していないかを確認します。- 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とコネクテッドコンテンツは、ターゲットホストが高い割合で著しい遅延や過負荷を経験し、タイムアウト、リクエスト過多、または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からノーブレークスペース（
またはUnicodeU+00A0）を除去します。URLがドキュメントやダッシュボードのフィールドからコピーされ、文字間にノーブレークスペースが挿入されていた場合、リクエストが失敗するか、使用可能なボディが返されない可能性があります。URLをプレーンテキストで再入力するか、隠れたスペースを削除してから、再度プレビューしてください。 - リダイレクト応答（
3xx）: コネクテッドコンテンツはリダイレクトに従いません。2xx応答のみが成功として扱われるため、301や302は同じURLがPostmanで動作する場合でも空白として表示されることがあります。最終的なリダイレクト先URLを使用するか、Brazeが呼び出すURLで2xx応答（通常は200）を返すようにエンドポイントを設定してください。エンドポイントがリダイレクトを返す場合にコネクテッドコンテンツが失敗するのはなぜですか？を参照してください。 - HTTPエラーと空のボディ:
2xx範囲外のステータスコードやブロックされたホストの場合、コネクテッドコンテンツは空の文字列をレンダリングすることがあります。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失敗イベントには含まれません。
詳細については、メッセージエンゲージメントイベント用語集を参照してください。