WhatsApp メッセージが届かなかった理由:failed ステータスとエラーの読み方
failed ステータスの Webhook は、事業者が API で送信したメッセージを Meta が送信も配信もできなかったことを意味します。messages フィールドに届き、status が failed で、code、title、message、error_data.details、href を含む errors 配列が付きます。code が理由を示します。131047 は 24 時間ウィンドウが閉じていること、131026 は配信不可、131049 はマーケティングの上限到達、131050 はマーケティング配信停止、131042 は支払いの問題です。
easyCoexistence は、WhatsApp Business アプリの番号を Coexistence 経由で Meta の Cloud API に接続し、failed ステータスをお使いのサーバーへ直接、またはオートメーションが有効な場合は署名付きの転送として渡します。
受信者が最後に返信してから 24 時間以上経過しています。Meta の対処法は、代わりにテンプレートを送信することです。
エコシステムのエンゲージメントを健全に保つため配信されていません。マーケティング用メッセージテンプレートを再送する前に、少なくとも 24 時間待ってください。
受信者はこの事業者からのマーケティング メッセージを停止することを選択しています。Meta は再試行しないよう案内しています。
failed ステータスには contacts 配列が含まれないため、statuses.id を使って失敗を照合してください。
Meta の課金は、メッセージが送信された時点ではなく、配信された時点で発生します。
failed ステータスはどのような形ですか?
通常のステータスと同じで、errors が加わります。contacts 配列はなく、メッセージを電話番号宛てに送った場合は recipient_user_id も含まれず、pricing オブジェクトもありません。title と message は同じ文言で、error_data.details が一文で説明し、href は Meta のエラーコード一覧を指します。以下は Meta 公式の例で、ユーザーごとの上限に達して停止されたマーケティング用メッセージテンプレートの場合です:
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "102290129340398",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "15550783881",
"phone_number_id": "106540352242922"
},
"statuses": [
{
"id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgARGBI0QUQ2MjA4NEYyRkExNjMyREUA",
"status": "failed",
"timestamp": "1751142888",
"recipient_id": "16505551234",
"errors": [
{
"code": 131049,
"title": "This message was not delivered to maintain healthy ecosystem engagement.",
"message": "This message was not delivered to maintain healthy ecosystem engagement.",
"error_data": {
"details": "In order to maintain a healthy ecosystem engagement, the message failed to be delivered."
},
"href": "/documentation/business-messaging/whatsapp/support/error-codes"
}
]
}
]
},
"field": "messages"
}
]
}
]
}最もよく返されるエラーコードと、その意味は?
Meta は送信レスポンス、failed ステータス、またはその両方でエラーを返します。同じコードがどちらでも届くことがあるため、ハンドラーは両方を確認してください。以下は、届かなかったメッセージの大半を説明するコードで、Meta 自身の理由と最初に試すべきことを示します。全一覧は Meta のエラーコードリファレンスにあります:
失敗の種類ごとに、ハンドラーはどう対応すべきですか?
再試行の前に、コードを次の対応に振り分けてください。一律に再試行すると、マーケティングの配信停止が繰り返しの失敗になり、ブロックを長引かせる可能性があります。一方で一時的なエラーを捨てると、1 分後には届いたはずのメッセージを失います。
- バックオフを使った再試行:131000(不明)、131016(サービス利用不可)、130429(スループット上限に到達)。
- 待機を優先:131049。少なくとも 24 時間待ってください。早期の再試行は、そのユーザーをさらに最大 24 時間ブロックすることがあります。
- メッセージを切り替える:131047 では、24 時間ウィンドウが閉じているため、承認済みテンプレートが必要です。
- この顧客への送信を停止:
user_preferencesの resume が届くまで、131050。 - アカウントまたはコンテンツを修正:131042 は支払い、131031 はアカウント制限、131053 はメディアの問題。
failed ステータスとしてしか現れない失敗は?
Meta が要求を受け付けた後に判断する失敗です。送信時には wamid が返り、拒否はあとからこの Webhook に届きます。Meta は、米国の市外局番を持つ電話番号(+1)の WhatsApp ユーザーには、マーケティング用メッセージテンプレートを配信しません。配信停止済みの顧客へのマーケティング用メッセージテンプレートは、処理された後に 131050 の failed として報告されます。ユーザーごとのマーケティング上限も同様に 131049 を報告します。
その番号に Webhook の送信先がない場合、これらの失敗はどこにも表示されず、メッセージは送信済みに見えるだけです。顧客に何も届かなかったときの確認手順の全体は、「メッセージが配信されない場合」のページを参照してください。
Coexistence の番号では何が変わりますか?
重要な点は 2 つあります。第一に、24 時間ウィンドウが適用されるのは API だけです。WhatsApp Business アプリから送信されたメッセージは、カスタマーサービスウィンドウの対象外だと、Meta の Coexistence ガイドに記載されています。そのため、131047 が出た後も、事業者は電話から顧客に返信できますが、システムは承認済みテンプレートを送信します。
第二に、スループットは固定です。アプリと API で同時に使う番号は毎秒最大 20 件までしか送信できず、それを超えると 130429 が返ります。それ以外は、通常の Cloud API 番号と同じです。同じフィールド、同じ errors 配列、同じコードです。
自動化と AI は失敗をどう捉えますか?
Meta がいつ拒否するかによります。送信時の拒否(131047 など)は、自動化のステップを失敗させます。「Runs」タブに「Failed」と Meta のメッセージが表示され、事業者にメールが届くので、その顧客に直接返信できます。また、自動化は自由形式の返信を送る前に受付ウィンドウを確認し、試みずに window_closed でスキップします。
Meta があとから報告する失敗は、「Forward URL」または直接の送信先に failed ステータスとして届き、実行結果は変わりません。MCP コネクタ経由でテンプレートを送った AI は、wamid と「sent: true」を確認します。システムに wamid のステータスを問い合わせるか、多くのメッセージが同時に失敗したときは、アシスタントに get_number_health を実行させてください。
よくある間違い
- 131050 をループで再試行すること。顧客がマーケティング メッセージを停止しているため、再開されるまで毎回同じ理由で失敗します。
- 131049 のマーケティング用メッセージテンプレートを数時間以内に再送すること。Meta は少なくとも 24 時間を求めており、早すぎる再試行はそのユーザーをさらに最大 24 時間ブロックすることがあります。
- title だけをログに残すこと。error_data.details に具体的な理由が入っているため、code と details を wamid と一緒に保存してください。
- Webhook の送信先がないまま、送信レスポンスだけで配信を判断すること。送信レスポンスが示すのは、Meta がメッセージを受け付けたことだけです。
送信時に自動化の返信が拒否されると、実行結果に Meta のエラーが表示され、メールが届きます。すべての番号は、切断と品質低下がないか 24 時間 365 日監視されます。料金は番号 1 件あたり月額 US$ 9 から US$ 0.75 まで(番号を増やすほど下がります)。最初の 3 日間は無料です。
よくある質問
Meta は failed になったメッセージに課金しますか?
Meta の料金ページによると、課金されるのは配信されたメッセージで、送信されただけのメッセージには課金されません。failed ステータスには pricing オブジェクトがありません。料金は事業者自身の WhatsApp Business Account に請求され、easyCoexistence が上乗せすることはありません。
131026 は、顧客がその事業者をブロックしたという意味ですか?
Meta の 131026 の一覧には、ほかの理由が挙げられています。番号が WhatsApp に登録されていない、受信者が最新の利用規約に同意していない、または WhatsApp のバージョンが古すぎる、というものです。Meta は、これらを別の手段で顧客に確認することを勧めています。
なぜ recipient_user_id は一部の失敗にだけ現れるのですか?
電話番号宛てに送信した場合、Meta は failed ステータスからこのフィールドを省略します。顧客の BSUID 宛てに送信した場合は、失敗にこのフィールドが含まれ、欠けるのは recipient_id の方かもしれません。
メッセージが配信された後に失敗することはありますか?
Meta のリファレンスでは、failed は送信または配信の失敗と定義されています。メッセージが端末に届いた後に期待できるステータスは、「read」、または音声メッセージの場合は「played」です。
続きを読む
始める準備はできましたか?
WhatsApp Coexistence の設定は数分で完了し、数か月もかかりません。スマートフォン上のアプリも引き続き使えます。
無料トライアルを始める確認日