コンテンツにスキップ

APIのエラーと応答

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

サーバーレスポンス

POSTペイロードがサーバーで受理された場合、成功メッセージとして以下のレスポンスが返されます。




{
  "message" : "success"
}

なお、success はRESTful APIペイロードが正しい形式であり、プッシュ通知やメールなどのメッセージングサービスに渡されたことのみを意味します。メッセージが実際に配信されたことを意味するものではありません。配信を妨げる別の要因（たとえば、デバイスがオフラインである、プッシュトークンがAppleのサーバーに拒否された、不明なユーザーIDが指定された、など）が存在する場合があります。

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

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

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

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




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

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




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

トラッキング対象の送信IDに対するレスポンス

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




{
  "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リクエストヘッダーがないか、正しくありません。設定ページで、値がapplication/jsonのContent-Typeを追加してください。
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の不正な構文や解析エラーが発生するのはなぜですか？を参照してください。

Brazeカスタマーエンゲージメントプラットフォームのドキュメント。

リソース
法的情報
会社情報
© 2026 Braze, Inc. All rights reserved.
Braze ステータスの確認
New Stuff!