Receiving Events

account.auth.failed

An authentication attempt failed.

アカウントの失敗イベント

WhatsApp の一部の account.auth.failed イベントには、任意の data.error オブジェクトが含まれます。存在する場合、code、numeric_code、message は空でない文字列です。HTTP エラーと区別してイベント内から読み取ります。

古いイベントや対象外のイベントには data.error がない場合があります。last_error との互換性を保ち、欠落や未知のコードは既存のアカウント失敗処理で扱います。アカウント一覧や詳細にこのオブジェクトが追加されるわけではありません。永久停止や復旧期限を示す分類ではありません。

安全に受け付けて処理を引き受けた後は、2xx で配信を確認します。アカウント失敗と HTTP 配信失敗は別です。アカウント失敗を理由に Webhook を拒否して再配信を発生させないでください。従来の再試行・再配信ルールを維持し、過去のイベントにエラーは補完されません。

account_auth_failed20100

アカウント認証に失敗しましたが、具体的な原因は不明です。既存の失敗処理を使い、制限やログアウトと推測しないでください。

対処と再試行: 現在の認証フローとユーザー操作の要否を確認します。この失敗だけを理由に認証を開始し直したり、期限切れ・終了済みセッションに再送信しないでください。

JSON の例です。message は実際の原因によって変わります

{
  "id": "<EVENT_ID>",
  "type": "account.auth.failed",
  "provider": "whatsapp",
  "account_id": "<ACCOUNT_ID>",
  "occurred_at": "2026-10-16T00:00:00Z",
  "data": {
    "auth_status": "failed",
    "runtime_status": "disconnected",
    "event": {
      "kind": "account_auth_status",
      "auth_status": "failed",
      "runtime_status": "disconnected"
    },
    "error": {
      "code": "account_auth_failed",
      "numeric_code": "20100",
      "message": "Account authentication failed. The specific cause could not be determined."
    }
  }
}

account_logged_out20101

現在のアカウントセッションは無効です。チャネルが対応する手順で再認証するようユーザーに案内します。

対処と再試行: チャネルが対応する手順で再認証するようユーザーに案内します。認証後に実行状態を別途照会し、接続の準備を確認してから接続が必要な操作を再開します。

JSON の例です。message は実際の原因によって変わります

{
  "id": "<EVENT_ID>",
  "type": "account.auth.failed",
  "provider": "whatsapp",
  "account_id": "<ACCOUNT_ID>",
  "occurred_at": "2026-10-16T00:00:00Z",
  "data": {
    "auth_status": "failed",
    "runtime_status": "disconnected",
    "event": {
      "kind": "account_auth_status",
      "auth_status": "failed",
      "runtime_status": "disconnected"
    },
    "error": {
      "code": "account_logged_out",
      "numeric_code": "20101",
      "message": "The account session is no longer valid. Reauthorization is required."
    }
  }
}

account_restricted20102

この WhatsApp の account.auth.failed イベントは data.error.code=account_restricted、numeric_code=20102 で現在のログイン制限を示します。永久停止や復旧可能な時刻を示すものではありません。

対処と再試行: 自動送信と再試行を停止し、公式 WhatsApp アプリで制限を確認・解消するようユーザーに案内します。解消と必要な再認証の後に再開してください。以前の running 状態は制限解除の証拠にはなりません。

JSON の例です。message は実際の原因によって変わります

{
  "id": "<EVENT_ID>",
  "type": "account.auth.failed",
  "provider": "whatsapp",
  "account_id": "<ACCOUNT_ID>",
  "occurred_at": "2026-10-16T00:00:00Z",
  "data": {
    "auth_status": "failed",
    "runtime_status": "disconnected",
    "event": {
      "kind": "account_auth_status",
      "auth_status": "failed",
      "runtime_status": "disconnected"
    },
    "error": {
      "code": "account_restricted",
      "numeric_code": "20102",
      "message": "Account login is restricted. Check the official WhatsApp app for details."
    }
  }
}

Event payload

{
  "id": "evt_auth_5e6f7a8b9c",
  "type": "account.auth.failed",
  "provider": "whatsapp",
  "account_id": "acc_8c21d0",
  "occurred_at": "2026-06-08T13:25:00Z",
  "data": {
    "auth_status": "failed",
    "runtime_status": "disconnected",
    "last_error": "logged_out_from_another_device",
    "event": {
      "kind": "account_auth_status",
      "auth_status": "failed"
    }
  }
}

注記

古いイベントや対象外のイベントには data.error がない場合があります。last_error との互換性を保ち、欠落や未知のコードは既存のアカウント失敗処理で扱います。アカウント一覧や詳細にこのオブジェクトが追加されるわけではありません。永久停止や復旧期限を示す分類ではありません。