Receiving Events

account.auth.failed

An authentication attempt failed.

Account failure events

Some WhatsApp account.auth.failed events include an optional data.error object with non-empty string fields code, numeric_code and message. Read these inside the event, separately from HTTP error responses.

Older events and other scopes may omit data.error. Preserve last_error compatibility and handle missing or unknown codes through the existing account-failure flow. Account list/detail responses do not gain this object. These classifications do not prove a permanent ban or a recovery deadline.

After securely accepting the event, return 2xx to acknowledge delivery. Account failures and HTTP delivery failures are separate: an account failure is not a reason to reject the webhook and trigger redelivery. Existing retry and replay rules still apply; historical events are not backfilled.

account_auth_failed20100

Account authorization failed, but the specific cause could not be determined. Use the existing failure flow without inventing a restriction or logout reason.

What to do: Query the current authorization flow and check whether user action is required. Do not start another authorization attempt merely because this request failed; do not resubmit an expired or finished session.

Illustrative JSON; message varies with the actual cause

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

The current account session is no longer valid. Ask the user to authorize again through the channel’s supported flow.

What to do: Ask the user to authorize again through this channel’s supported flow. After authorization, query runtime state and confirm the connection before resuming dependent operations.

Illustrative JSON; message varies with the actual cause

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

This WhatsApp account.auth.failed event identifies a current login restriction with data.error.code=account_restricted and numeric_code=20102. It does not prove a permanent ban or state when recovery will be possible.

What to do: Stop automatic sends and retries, and ask the user to inspect and resolve the restriction in the official WhatsApp app. Resume only after resolution and any required reauthorization. A previously running connection does not prove the restriction has cleared.

Illustrative JSON; message varies with the actual cause

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

Notes

Older events and other scopes may omit data.error. Preserve last_error compatibility and handle missing or unknown codes through the existing account-failure flow. Account list/detail responses do not gain this object. These classifications do not prove a permanent ban or a recovery deadline.