ログイン無料トライアルを開始
Meta Tech Provider

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 ステータスをお使いのサーバーへ直接、またはオートメーションが有効な場合は署名付きの転送として渡します。

131047

受信者が最後に返信してから 24 時間以上経過しています。Meta の対処法は、代わりにテンプレートを送信することです。

131049

エコシステムのエンゲージメントを健全に保つため配信されていません。マーケティング用メッセージテンプレートを再送する前に、少なくとも 24 時間待ってください。

131050

受信者はこの事業者からのマーケティング メッセージを停止することを選択しています。Meta は再試行しないよう案内しています。

No contacts

failed ステータスには contacts 配列が含まれないため、statuses.id を使って失敗を照合してください。

Delivered

Meta の課金は、メッセージが送信された時点ではなく、配信された時点で発生します。

failed ステータスはどのような形ですか?

通常のステータスと同じで、errors が加わります。contacts 配列はなく、メッセージを電話番号宛てに送った場合は recipient_user_id も含まれず、pricing オブジェクトもありません。title と message は同じ文言で、error_data.details が一文で説明し、href は Meta のエラーコード一覧を指します。以下は Meta 公式の例で、ユーザーごとの上限に達して停止されたマーケティング用メッセージテンプレートの場合です:

Meta's example: a message that failed with 131049
{
  "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 のエラーコードリファレンスにあります:

131026Undeliverable: not a WhatsApp number, terms not accepted, or an outdated WhatsApp version on the recipient's phone.
131047More than 24 hours since the customer last wrote. Send an approved template instead.
131049Held back to keep engagement healthy, usually the per-user marketing limit. Wait 24 hours or more.
131050The customer stopped marketing messages from you. Do not retry.
131042A problem with the payment method on the WhatsApp Business Account.
130472Not sent because the recipient is part of Meta's marketing message experiment.
131053Media could not be uploaded, often an unsupported file type.
131000Unknown error. Try again; if it persists, open a Direct Support ticket.

失敗の種類ごとに、ハンドラーはどう対応すべきですか?

再試行の前に、コードを次の対応に振り分けてください。一律に再試行すると、マーケティングの配信停止が繰り返しの失敗になり、ブロックを長引かせる可能性があります。一方で一時的なエラーを捨てると、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 がメッセージを受け付けたことだけです。
EasyCoexistence で実現する

送信時に自動化の返信が拒否されると、実行結果に 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 の設定は数分で完了し、数か月もかかりません。スマートフォン上のアプリも引き続き使えます。

無料トライアルを始める

確認日