APIエラーと応答
このリファレンス記事では、Braze APIの使用中に発生する可能性のあるさまざまなエラーとサーバー応答、およびそれらのトラブルシューティング方法について説明します。
サーバーの応答
POST ペイロードがサーバーで受け付けられた場合、成功したメッセージには次の応答が返されます。
{
"message" : "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 エラーは、サーバーが上流の別のサーバーからレスポンスを受信しなかったことを示します。
致命的なエラー

401 および 403 エラーの場合は、Authorization ヘッダーの Bearer トークン、ワークスペースのインスタンスの REST エンドポイント、および API キーの権限を確認してください。400 の解析エラーの場合は、リクエスト本文の JSON エンコーディングを検証してください。詳細については、リクエスト本文の解析中のエラーを参照してください。/users/track のオブジェクト制限については、/users/track のレート制限を参照してください。リクエストサイズの制限については、ペイロードサイズの制限を参照してください。レート制限 (429) については、レート制限で別途説明しています。
リクエストで致命的なエラーが発生した場合、次のステータスコードと関連するエラーメッセージが返されます。

以下のエラーコードはすべて、メッセージが送信されないことを示します。
| エラーコード | 説明 |
|---|---|
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 Bad Request (transactional campaign) |
トランザクションキャンペーンはこのエンドポイントからトリガーできません。代わりに /transactional/v1/campaigns/{campaign_id}/send エンドポイントを使用してください。campaign_id がトランザクションメールキャンペーンに属している場合に、/campaigns/trigger/send および /campaigns/trigger/schedule/create から返されます。 |
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 の場合、このエラーは1回のリクエストで許可されるオブジェクトの最大数を超えたことが原因です。上限はレート制限モデルによって異なります。ほとんどの顧客の場合、各リクエストでは 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 キーに十分な権限がありません。主な原因は次のとおりです。
|
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 エンコードされたオブジェクトではなく連結された文字列の送信などがあります。
再試行する前に、次の点を確認してください。
- JSON リンターでペイロードを検証します。
Content-Type: application/jsonを設定し、UTF-8 でエンコードされた JSON を送信します。- HTTP クライアントが生の文字列を連結するのではなく、オブジェクトを JSON エンコードしていることを確認します。
/users/track のペイロードサイズとリクエストあたりのオブジェクト制限については、構文エラーまたは解析エラーで 400 Bad Request が返されるのはなぜですか?を参照してください。