APIのエラーと応答

この参考記事では、Braze APIの使用中に発生する可能性のあるさまざまなエラーとサーバー応答、およびそれらのトラブルシューティング方法について説明します。

サーバーレスポンス

POST ペイロードが Braze のサーバーで受け付けられた場合、メッセージが成功すると次のレスポンスが返されます。

1
2
3

{
  "message" : "success"
}

success は、RESTful API ペイロードが正しく構成され、プッシュ通知、メール、またはその他のメッセージングサービスに渡されたことのみを意味します。メッセージが実際に配信されたことを意味するものではありません。デバイスがオフラインである、プッシュトークンが Apple のサーバーで拒否された、不明なユーザー ID が指定されたなど、メッセージの配信を妨げる要因が他にもあるためです。

メッセージが配信されていないのにリクエストが success を返すのはなぜですか？

message: success または 2XX のレスポンスは、Braze が対象のエンドポイントへのリクエストを受け付けてキューに入れたことを意味します。すべての受信者がメッセージを受け取ったことを意味するものではありません。メッセージングの場合、配信はチャネルの適格性、トークン、プロバイダーのエラー、コンテンツの検証にも左右されます。送信をブロックする HTTP エラーについては致命的なエラーの表を、その後の配信指標についてはキャンペーンまたはキャンバスの分析を参照してください。

/users/identify のようにメッセージを送信しないエンドポイントの場合、success レスポンスは Braze がリクエストを処理用に受け付けたことのみを意味します。指定したエイリアスを持つユーザーが存在しない場合や、エイリアスがすでに external_id を持つプロファイルに属している場合、Braze は identify をスキップします。それでも API は最初の success レスポンスを返し、エイリアスが一致しなかったことを示すエラーは返されません。alias_name は大文字と小文字を区別するため、大文字と小文字が一致しない場合も同じ結果になります。

メッセージが成功しても致命的でないエラーがある場合は、次のレスポンスが返されます。

1
2
3

{
  "message" : "success", "errors" : [<minor error message>]
}

成功した場合、errors 配列内のエラーの影響を受けなかったメッセージは引き続き配信されます。メッセージに致命的なエラーがある場合は、次のレスポンスが返されます。

1
2
3

{
  "message" : <fatal error message>, "errors" : [<minor error message>]
}

追跡対象の送信 ID に対するレスポンス

キャンペーンの分析はいつでも利用できます。さらに、キャンペーンがブロードキャストとして送信された場合は、特定のキャンペーン送信インスタンスの分析も利用できます。特定のキャンペーン送信インスタンスのトラッキングが利用可能な場合は、次のレスポンスが返されます。

1
2
3

{
  "message": "success", "send_id" : "example_send_id"
}

返された送信 ID は、/send/data_series エンドポイントのパラメーターとして使用でき、送信ごとの分析を取得できます。

エラー

サーバーレスポンスのステータスコード要素は3桁の数字で、最初の桁がレスポンスのクラスを表します。

• 2XX クラスのステータスコード (非致命的) は、リクエストが正常に受信、理解、受け入れられたことを示します。
• 4XX クラスのステータスコード (致命的) は、クライアントエラーを示します。4XX エラーコードとその説明の一覧については、致命的なエラーの表を参照してください。
• 5XX クラスのステータスコード (致命的) は、サーバーエラーを示します。考えられる原因はいくつかあります。たとえば、アクセスしようとしているサーバーがリクエストを実行できない、サーバーがメンテナンス中のためリクエストを実行できない、サーバーのトラフィックが高負荷になっている、などです。この場合は、エクスポネンシャルバックオフを使用してリクエストを再試行することをお勧めします。インシデントや障害が発生した場合、Braze はインシデント期間中に失敗した REST API 呼び出しを再実行できません。インシデント期間中に失敗した呼び出しは、お客様自身で再試行する必要があります。
  • 502 エラーは、宛先サーバーに到達する前に失敗したことを意味します。
  • 503 エラーは、リクエストが宛先サーバーに到達したものの、容量不足やネットワークの問題などの理由でリクエストを完了できないことを意味します。
  • 504 エラーは、サーバーが上流の別のサーバーからレスポンスを受け取れなかったことを示します。

致命的なエラー

リクエストで致命的なエラーが発生した場合、次のステータスコードと関連するエラーメッセージが返されます。

警告

以下のエラーコードはすべて、メッセージが送信されないことを示します。

リクエスト本文の解析中のエラー

リクエスト本文が有効な JSON でない場合、Braze は HTTP 400 を返します。これは、POST、PUT、PATCH など、JSON 本文を受け付ける REST エンドポイントに適用されます。

error フィールドには、リクエスト本文に有効な application/json を渡す必要があるというメッセージが含まれます。Error while parsing request body. Please check your syntax. が表示される場合もあります。

一般的な原因としては、末尾のカンマ、JSON 内のコメント、単一引用符で囲まれた文字列、ペイロードの前の余分な {、JSON エンコードされたオブジェクトではなく連結された文字列の送信などがあります。

再試行する前に、次の点を確認してください。

1. JSON リンターでペイロードを検証します。
2. Content-Type: application/json を設定し、UTF-8 でエンコードされた JSON を送信します。
3. HTTP クライアントが生の文字列を連結するのではなく、オブジェクトを JSON エンコードしていることを確認します。

/users/track のペイロードサイズとリクエストあたりのオブジェクト数の上限については、構文エラーまたは解析エラーで 400 Bad Request が返されるのはなぜですか?を参照してください。