Receiving Events

account.auth.failed

An authentication attempt failed.

Sự kiện lỗi tài khoản

Một số sự kiện WhatsApp account.auth.failed có đối tượng data.error tùy chọn, với code, numeric_code và message là chuỗi không rỗng. Đọc trong sự kiện và xử lý riêng với phản hồi lỗi HTTP.

Sự kiện cũ hoặc ngoài phạm vi có thể không có data.error. Giữ tương thích last_error; mã thiếu hoặc lạ dùng quy trình lỗi tài khoản hiện có. Danh sách và chi tiết tài khoản không được thêm đối tượng này. Phân loại này không xác nhận khóa vĩnh viễn hay thời hạn khôi phục.

Sau khi tiếp nhận an toàn và chấp nhận xử lý, vẫn trả 2xx để xác nhận giao. Lỗi tài khoản khác lỗi giao HTTP; không từ chối webhook chỉ vì tài khoản lỗi và gây giao lại. Quy tắc thử lại/phát lại cũ vẫn áp dụng, không bổ sung lỗi cho sự kiện lịch sử.

account_auth_failed20100

Xác thực tài khoản thất bại nhưng chưa xác định nguyên nhân cụ thể. Dùng luồng lỗi hiện có, không tự suy ra bị hạn chế hay đăng xuất.

Xử lý và thử lại: Truy vấn luồng xác thực hiện tại và xem có cần người dùng thao tác không. Không bắt đầu xác thực mới chỉ vì yêu cầu này lỗi; không gửi lại vào phiên hết hạn hoặc đã kết thúc.

JSON minh họa; message thay đổi theo nguyên nhân thực tế

{
  "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

Phiên tài khoản hiện tại không còn hiệu lực. Hướng dẫn người dùng xác thực lại theo luồng kênh hỗ trợ.

Xử lý và thử lại: Hướng dẫn người dùng xác thực lại qua luồng kênh hỗ trợ. Sau đó kiểm tra runtime và xác nhận kết nối sẵn sàng trước khi tiếp tục thao tác cần kết nối.

JSON minh họa; message thay đổi theo nguyên nhân thực tế

{
  "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

Sự kiện WhatsApp account.auth.failed này xác định hạn chế đăng nhập hiện tại qua data.error.code=account_restricted và numeric_code=20102. Không xác nhận khóa vĩnh viễn hay thời điểm khôi phục.

Xử lý và thử lại: Dừng gửi và thử lại tự động, hướng dẫn người dùng kiểm tra và xử lý hạn chế trong ứng dụng WhatsApp chính thức. Chỉ tiếp tục sau khi giải quyết và xác thực lại nếu cần; trạng thái running trước đó không chứng minh hạn chế đã hết.

JSON minh họa; message thay đổi theo nguyên nhân thực tế

{
  "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"
    }
  }
}

Ghi chú

Sự kiện cũ hoặc ngoài phạm vi có thể không có data.error. Giữ tương thích last_error; mã thiếu hoặc lạ dùng quy trình lỗi tài khoản hiện có. Danh sách và chi tiết tài khoản không được thêm đối tượng này. Phân loại này không xác nhận khóa vĩnh viễn hay thời hạn khôi phục.