Skip to content

APIのエラーと応答

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

サーバーレスポンス

POST ペイロードがサーバーに受け入れられた場合、成功したメッセージには以下のレスポンスが返されます。

1
2
3

{
  "message" : "success"
}

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

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

message: success または 2XX レスポンスは、Braze が関連するエンドポイントのリクエストを受け入れてキューに入れたことを意味します。すべての受信者がメッセージを受け取ったことを意味するものではありません。メッセージングの場合、配信はチャネルの適格性、トークン、プロバイダーエラー、およびコンテンツのバリデーションに依存します。送信をブロックする HTTP エラーについては致命的なエラーテーブルを参照し、ダウンストリームの配信指標についてはキャンペーンまたはキャンバスの分析を確認してください。

メッセージを送信しない/users/identifyのようなエンドポイントの場合、成功メッセージは Braze がリクエストを処理のために受信したことのみを意味します。処理後にエイリアスに一致するものがない場合、リクエストは停止されます。

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

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エラーは、サーバーが上流の別のサーバーからレスポンスを受信しなかったことを示します。

致命的エラー

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

エラーコード 説明
5XX Internal Server Error 指数バックオフを使用してリクエストを再試行してください。
400 Bad Request 構文不正。無効なJSONはHTTP 400を返します。errorフィールドには、リクエストボディに有効なapplication/jsonを渡す必要があるというメッセージ、またはError while parsing request body. Please check your syntax.が含まれる場合があります。リクエストボディの解析エラーを参照してください。
400 No Recipients リクエストにexternal ID、セグメントID、またはプッシュトークンがありません。
400 Invalid キャンペーン ID 指定されたキャンペーンIDに対応するメッセージングAPIキャンペーンが見つかりません。
400 Message Variant Unspecified キャンペーンIDは指定されていますが、メッセージバリアントIDが指定されていません。
400 Invalid Message Variant 有効なキャンペーンIDが指定されていますが、メッセージバリアントIDがそのキャンペーンのメッセージのいずれとも一致しません。
400 Mismatched Message Type 少なくとも1つのメッセージに対して、誤ったメッセージタイプのメッセージバリアントが指定されています。
400 Invalid Extra Push Payload apple_pushまたはandroid_pushにextraキーが指定されていますが、ディクショナリではありません。
400 Max Input Length Exceeded /users/trackの場合、このエラーは単一のリクエストで許可されるオブジェクトの最大数を超えたことが原因です。制限はレートリミットモデルによって異なります。ほとんどのお客様の場合、各リクエストはattributes、events、purchasesを合わせて最大75個のオブジェクトをサポートします。レガシーレートリミットを使用しているお客様の場合、各配列は最大75個のオブジェクトを独立してサポートします。詳細については、POST：ユーザーの作成と更新を参照してください。
400 The max number of external_ids and aliases per request was exceeded 50個を超えるexternal IDを呼び出したことが原因です。
400 The max number of ids per request was exceeded 50個を超えるexternal IDを呼び出したことが原因です。
400 No message to send メッセージのペイロードが指定されていません。
400 Slideup Message Length Exceeded スライドアップメッセージが140文字を超えています。
400 Apple Push Length Exceeded JSONペイロードが1,912バイトを超えています。
400 Android Push Length Exceeded JSONペイロードが4,000バイトを超えています。
400 Bad Request send_atの日時を解析できません。
400 Bad Request リクエストでin_local_timeがtrueに設定されていますが、会社のタイムゾーンではtimeがすでに過ぎています。
401 Unauthorized 無効なAPIキーです。一般的な原因は次のとおりです。

- Authorizationヘッダーの欠落または不正な形式。ヘッダーの値はBearerの後にスペース、続いてAPIキーの形式にする必要があります：Authorization: Bearer YOUR-API-KEY。よくある間違いには、Bearerの省略、Bearerの後のキーの省略、値を引用符で囲むことなどがあります。
- RESTエンドポイントの誤り。リクエストを間違ったインスタンスに送信しています。たとえば、アカウントがEUインスタンス（https://dashboard-01.braze.eu）にある場合、リクエストはhttps://rest.fra-01.braze.euに送信する必要があります。
- 権限の不足。各APIキーは特定のワークスペースと権限のセットにスコープされています。ダッシュボードの設定 > APIキーでキーの権限を確認してください。
- APIキーの誤り。APIキーはワークスペース固有です。あるワークスペースのキーを別のワークスペースのリクエストの認証に使用することはできません。
403 Forbidden 料金プランがサポートしていないか、アカウントが無効化されています。
403 Access Denied 使用しているREST APIキーに十分な権限がありません。一般的な原因は次のとおりです。
  • APIキーが機能より前に作成された。APIキーが機能のリリース前（購読グループやカタログなど）に作成された場合、キーはそれらの権限を自動的に継承しません。設定 > APIキーで必要な権限を持つ新しいAPIキーを作成してください。
  • エンドポイント固有の権限の欠落。各APIエンドポイントには特定の権限スコープが必要です（たとえば、users.trackやemail.status）。キーの権限が呼び出しているエンドポイントと一致していることを確認してください。
  • URLの末尾のスラッシュまたはタイプミス。たとえば、/users/trackの代わりに/users/track/（末尾にスラッシュあり）を使用すると、予期しないエラーが発生する可能性があります。
404 Not Found 無効なURLです。
415 Unsupported Media Type Content-Typeリクエストヘッダーが欠落しているか、正しくありません。設定ページで、Content-Typeを値application/jsonで追加してください。
429 Rate Limited レートリミットを超えています。

リクエストボディの解析エラー

リクエストボディが有効な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が返されるのはなぜですか？を参照してください。
New Stuff!