接收事件

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 兼容，缺失或未知码沿用现有账号失败流程。账号列表或详情不会因此新增此对象。这些分类不证明永久封禁，也不提供恢复期限。