接收事件

account.auth.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."
    }
  }
}

事件載荷

{
  "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 相容，缺失或未知碼沿用既有帳號失敗流程。帳號列表或詳情不會因此新增此物件。這些分類不證明永久封禁，也不提供恢復期限。