Error reference

Provide provider_data.phone when creating the account for this authorization mode.

What to do: Correct the parameters for this operation and channel before requesting again. Repeating an unchanged invalid request will not resolve the error.

{
  "request_id": "req_example",
  "error": {
    "code": "auth_mode_phone_required",
    "numeric_code": "20019",
    "message": "Phone number is required for this auth mode"
  }
}

The operation was rejected. Check the request and keep request_id for diagnosis.

What to do: List or query existing resources to check whether creation already took effect before creating another. Correct the underlying cause and keep request_id; do not create duplicates automatically.

{
  "request_id": "req_example",
  "error": {
    "code": "create_api_key_failed",
    "numeric_code": "11101",
    "message": "Failed to create API key"
  }
}

type must be user, group or channel.

What to do: Correct the parameters for this operation and channel before requesting again. Repeating an unchanged invalid request will not resolve the error.

{
  "request_id": "req_example",
  "error": {
    "code": "invalid_conversation_type",
    "numeric_code": "37000",
    "message": "Field 'type' must be one of: user, group, channel"
  }
}

Check the channel identifier in the URL.

What to do: Correct the parameters for this operation and channel before requesting again. Repeating an unchanged invalid request will not resolve the error.

{
  "request_id": "req_example",
  "error": {
    "code": "invalid_provider",
    "numeric_code": "30000",
    "message": "Invalid provider parameter"
  }
}

The reply token cannot be read. Copy data.message.reply_token from the inbound event unchanged.

What to do: Correct the parameters for this operation and channel before requesting again. Repeating an unchanged invalid request will not resolve the error.

{
  "request_id": "req_example",
  "error": {
    "code": "invalid_reply_token",
    "numeric_code": "36006",
    "message": "Invalid or unreadable reply_token"
  }
}

Check the JSON body and required fields.

What to do: Correct the parameters for this operation and channel before requesting again. Repeating an unchanged invalid request will not resolve the error.

{
  "request_id": "req_example",
  "error": {
    "code": "invalid_request",
    "numeric_code": "10000",
    "message": "Invalid request parameters"
  }
}

The workspace override target is empty or malformed. Remove the override header and use the API key belonging to the intended workspace.

What to do: Correct the parameters for this operation and channel before requesting again. Repeating an unchanged invalid request will not resolve the error.

{
  "request_id": "req_example",
  "error": {
    "code": "invalid_target_workspace",
    "numeric_code": "11003",
    "message": "Invalid target workspace"
  }
}

Check the channel-specific fields and formats.

What to do: Correct the parameters for this operation and channel before requesting again. Repeating an unchanged invalid request will not resolve the error.

{
  "request_id": "req_example",
  "error": {
    "code": "provider_invalid_request",
    "numeric_code": "30001",
    "message": "Provider rejected the request"
  }
}

The operation was rejected. Check the request and keep request_id for diagnosis.

What to do: Check the target key under the current workspace before changing or rotating it. A missing target is not repaired by retrying. After an unknown rotation result, confirm which credentials remain usable without exposing key material.

{
  "request_id": "req_example",
  "error": {
    "code": "rotate_api_key_failed",
    "numeric_code": "11103",
    "message": "Failed to rotate API key"
  }
}

This account action is not recognized; use a documented action.

What to do: Use a channel and action listed as supported. Repeating the same request does not add capabilities or grant beta access.

{
  "request_id": "req_example",
  "error": {
    "code": "unsupported_action",
    "numeric_code": "30005",
    "message": "Action not supported"
  }
}

The channel does not support this operation; choose a supported operation.

What to do: Use a channel and action listed as supported. Repeating the same request does not add capabilities or grant beta access.

{
  "request_id": "req_example",
  "error": {
    "code": "unsupported_conversation_type",
    "numeric_code": "37001",
    "message": "Operation not supported for this conversation type"
  }
}

Choose a message.type supported by this channel.

What to do: Use a channel and action listed as supported. Repeating the same request does not add capabilities or grant beta access.

{
  "request_id": "req_example",
  "error": {
    "code": "unsupported_message_type",
    "numeric_code": "36000",
    "message": "Message type not supported"
  }
}

Choose an auth_mode supported by this channel.

What to do: Use a channel and action listed as supported. Repeating the same request does not add capabilities or grant beta access.

{
  "request_id": "req_example",
  "error": {
    "code": "unsupported_provider_auth_mode",
    "numeric_code": "20018",
    "message": "Auth mode not supported by this provider"
  }
}

The operation was rejected. Check the request and keep request_id for diagnosis.

What to do: Check the target key under the current workspace before changing or rotating it. A missing target is not repaired by retrying. After an unknown rotation result, confirm which credentials remain usable without exposing key material.

{
  "request_id": "req_example",
  "error": {
    "code": "update_api_key_failed",
    "numeric_code": "11102",
    "message": "Failed to update API key"
  }
}

The operation was rejected. Check the request and keep request_id for diagnosis.

What to do: Read the current resource state and confirm the previous outcome before repeating this change. Keep request_id; do not automatically repeat a write whose outcome is unknown.

{
  "request_id": "req_example",
  "error": {
    "code": "update_workspace_failed",
    "numeric_code": "41001",
    "message": "Failed to update workspace"
  }
}

Check the wallet account request and any optional Idempotency-Key header.

What to do: Correct the parameters for this operation and channel before requesting again. Repeating an unchanged invalid request will not resolve the error.

{
  "request_id": "req_example",
  "error": {
    "code": "wallet_invalid_request",
    "numeric_code": "20021",
    "message": "Invalid wallet account request"
  }
}

Check whether the API key is correct and enabled.

What to do: Keep request_id and the structured codes, and investigate the current operation before taking another action.

{
  "request_id": "req_example",
  "error": {
    "code": "invalid_api_key",
    "numeric_code": "11001",
    "message": "Invalid API key"
  }
}

Add the X-Api-Key header.

What to do: Keep request_id and the structured codes, and investigate the current operation before taking another action.

{
  "request_id": "req_example",
  "error": {
    "code": "missing_api_key",
    "numeric_code": "11000",
    "message": "Missing X-Api-Key header"
  }
}

The workspace needs private-beta access for calling APIs and explicit call-event subscriptions.

What to do: Keep request_id and the structured codes, and investigate the current operation before taking another action.

{
  "request_id": "req_example",
  "error": {
    "code": "beta_feature_not_enabled",
    "numeric_code": "41002",
    "message": "Beta feature not enabled"
  }
}

The CORS origin, method or headers are not allowed. Check the calling environment.

What to do: Keep request_id and the structured codes, and investigate the current operation before taking another action.

{
  "request_id": "req_example",
  "error": {
    "code": "cors_forbidden",
    "numeric_code": "11009",
    "message": "CORS preflight request is not allowed"
  }
}

Posts & Comments

Check the account and the target identifiers actually required by this endpoint. post_not_found confirms that the post is missing. comment_not_found means the target top-level comment was not found after verification, not that all replies were searched. post_inaccessible means inaccessible; it does not prove absence or identify the cause. Keep the error and investigate before choosing the next action.

What to do: Check the target identifier, resource ownership and current workspace. Do not treat a confirmed missing or inaccessible target as a temporary service failure to retry automatically.

{
  "request_id": "req_example",
  "error": {
    "code": "post_inaccessible",
    "numeric_code": "39005",
    "message": "Post is not accessible"
  }
}

The request attempts a workspace override that this API key is not allowed to use. Remove the override header and use the API key belonging to the intended workspace.

What to do: Keep request_id and the structured codes, and investigate the current operation before taking another action.

{
  "request_id": "req_example",
  "error": {
    "code": "workspace_override_forbidden",
    "numeric_code": "11002",
    "message": "Workspace override is not allowed"
  }
}

Check account_id and use an X-Api-Key for the workspace that owns the account. An account not found in this workspace cannot be accessed with this key.

What to do: Check the target identifier, resource ownership and current workspace. Do not treat a confirmed missing or inaccessible target as a temporary service failure to retry automatically.

{
  "request_id": "req_example",
  "error": {
    "code": "account_not_found",
    "numeric_code": "20020",
    "message": "Account not found"
  }
}

The operation is absent or outside this workspace. Check the original operation_id and API key scope.

What to do: Check the target identifier, resource ownership and current workspace. Do not treat a confirmed missing or inaccessible target as a temporary service failure to retry automatically.

{
  "request_id": "req_example",
  "error": {
    "code": "account_operation_not_found",
    "numeric_code": "20029",
    "message": "Account operation not found"
  }
}

Calls

The call does not exist under this account and workspace.

What to do: Check the target identifier, resource ownership and current workspace. Do not treat a confirmed missing or inaccessible target as a temporary service failure to retry automatically.

{
  "request_id": "req_example",
  "error": {
    "code": "call_not_found",
    "numeric_code": "38003",
    "message": "Call not found"
  }
}

Posts & Comments

Check the account and the target identifiers actually required by this endpoint. post_not_found confirms that the post is missing. comment_not_found means the target top-level comment was not found after verification, not that all replies were searched. post_inaccessible means inaccessible; it does not prove absence or identify the cause. Keep the error and investigate before choosing the next action.

What to do: Check the target identifier, resource ownership and current workspace. Do not treat a confirmed missing or inaccessible target as a temporary service failure to retry automatically.

{
  "request_id": "req_example",
  "error": {
    "code": "comment_not_found",
    "numeric_code": "39001",
    "message": "Comment not found"
  }
}

The contact was not found under this account; check the identifier.

What to do: Check the target identifier, resource ownership and current workspace. Do not treat a confirmed missing or inaccessible target as a temporary service failure to retry automatically.

{
  "request_id": "req_example",
  "error": {
    "code": "contact_not_found",
    "numeric_code": "35000",
    "message": "Contact not found"
  }
}

The channel could not find this conversation; check the identifier and account.

What to do: Check the target identifier, resource ownership and current workspace. Do not treat a confirmed missing or inaccessible target as a temporary service failure to retry automatically.

{
  "request_id": "req_example",
  "error": {
    "code": "conversation_not_found",
    "numeric_code": "37002",
    "message": "Conversation not found"
  }
}

The group was not found under this account; check the group ID.

What to do: Check the target identifier, resource ownership and current workspace. Do not treat a confirmed missing or inaccessible target as a temporary service failure to retry automatically.

{
  "request_id": "req_example",
  "error": {
    "code": "group_not_found",
    "numeric_code": "34004",
    "message": "Group not found"
  }
}

Check the API path and method.

What to do: Check the target identifier, resource ownership and current workspace. Do not treat a confirmed missing or inaccessible target as a temporary service failure to retry automatically.

{
  "request_id": "req_example",
  "error": {
    "code": "not_found",
    "numeric_code": "10001",
    "message": "Endpoint not found"
  }
}

Posts & Comments

Check the account and the target identifiers actually required by this endpoint. post_not_found confirms that the post is missing. comment_not_found means the target top-level comment was not found after verification, not that all replies were searched. post_inaccessible means inaccessible; it does not prove absence or identify the cause. Keep the error and investigate before choosing the next action.

What to do: Check the target identifier, resource ownership and current workspace. Do not treat a confirmed missing or inaccessible target as a temporary service failure to retry automatically.

{
  "request_id": "req_example",
  "error": {
    "code": "post_not_found",
    "numeric_code": "39000",
    "message": "Post not found"
  }
}

The overridden workspace was not found or is unavailable. Verify workspace ownership, remove the override header and use the intended workspace’s API key; repeated requests do not grant access.

What to do: Check the target identifier, resource ownership and current workspace. Do not treat a confirmed missing or inaccessible target as a temporary service failure to retry automatically.

{
  "request_id": "req_example",
  "error": {
    "code": "target_workspace_not_found",
    "numeric_code": "11004",
    "message": "Target workspace not found"
  }
}

Account allocation is busy; retry after a short delay.

What to do: Keep request_id and the structured codes, and investigate the current operation before taking another action.

{
  "request_id": "req_example",
  "error": {
    "code": "account_allocation_busy",
    "numeric_code": "20011",
    "message": "Allocation is busy in the current region; please retry later"
  }
}

The account has already completed authorization and this action refuses duplicate authorization. Refresh the authorization state and reuse the completed result; do not repeatedly authorize or cancel in a loop.

What to do: Keep request_id and the structured codes, and investigate the current operation before taking another action.

{
  "request_id": "req_example",
  "error": {
    "code": "account_already_authorized",
    "numeric_code": "20016",
    "message": "Account is already authorized; re-authentication is not required"
  }
}

The account has no active channel connection binding; check its status.

What to do: Query authorization and runtime status, then choose refresh, start or reconnect only when appropriate for the intended state and channel. A connection problem alone does not prove logout. Confirm running before dependent business operations.

{
  "request_id": "req_example",
  "error": {
    "code": "account_binding_not_found",
    "numeric_code": "30006",
    "message": "Account is not bound to an available server"
  }
}

Webhook Endpoints

List the account’s independent endpoints using account_id and update the existing active endpoint. To switch, deactivate the old active endpoint before activating another. Do not automatically retry creation or reactivation.

What to do: Read the endpoint configuration and account scope before resubmitting. PATCH replaces settings; retain the intended subscriptions, signing configuration and retry policy. For an active-endpoint conflict, update the existing endpoint or deactivate it before enabling another.

{
  "request_id": "req_example",
  "error": {
    "code": "account_webhook_already_exists",
    "numeric_code": "40008",
    "message": "Account already has an active webhook endpoint"
  }
}

The workspace price or pricing basis changed. Confirm the original result, then request a new quote.

What to do: Keep request_id and the structured codes, and investigate the current operation before taking another action.

{
  "request_id": "req_example",
  "error": {
    "code": "billing_quote_changed",
    "numeric_code": "20027",
    "message": "Pricing changed; request a new quote"
  }
}

The quote expired. Confirm any earlier creation result before requesting another quote.

What to do: Keep request_id and the structured codes, and investigate the current operation before taking another action.

{
  "request_id": "req_example",
  "error": {
    "code": "billing_quote_expired",
    "numeric_code": "20026",
    "message": "Billing quote expired"
  }
}

The quote does not match this workspace or request. Confirm the original result, then obtain a matching quote.

What to do: Keep request_id and the structured codes, and investigate the current operation before taking another action.

{
  "request_id": "req_example",
  "error": {
    "code": "billing_quote_invalid",
    "numeric_code": "20025",
    "message": "Billing quote does not match this request"
  }
}

Calls

The account already has a managed active call. Check the known call and the intended action; this error alone does not instruct you to end a call or repeatedly query the same failing operation.

What to do: Keep request_id and the structured codes, and investigate the current operation before taking another action.

{
  "request_id": "req_example",
  "error": {
    "code": "call_already_active",
    "numeric_code": "38000",
    "message": "Account already has an active call"
  }
}

This channel identity is already connected to another account in this workspace.

What to do: Keep request_id and the structured codes, and investigate the current operation before taking another action.

{
  "request_id": "req_example",
  "error": {
    "code": "duplicate_provider_account",
    "numeric_code": "20015",
    "message": "A provider account with the same identity already exists in this workspace"
  }
}

No capacity is available in this region; query regions for an allocatable option.

What to do: Keep request_id and the structured codes, and investigate the current operation before taking another action.

{
  "request_id": "req_example",
  "error": {
    "code": "no_allocatable_server",
    "numeric_code": "20013",
    "message": "No allocatable server in the current region"
  }
}

The channel identity in the request does not match the account binding.

What to do: Keep request_id and the structured codes, and investigate the current operation before taking another action.

{
  "request_id": "req_example",
  "error": {
    "code": "provider_account_mismatch",
    "numeric_code": "20017",
    "message": "Authenticated provider account does not match the bound account; re-scan with the original account"
  }
}

The connection is not ready. Check authorization and runtime_status before retrying.

What to do: Query authorization and runtime status, then choose refresh, start or reconnect only when appropriate for the intended state and channel. A connection problem alone does not prove logout. Confirm running before dependent business operations.

{
  "request_id": "req_example",
  "error": {
    "code": "provider_not_ready",
    "numeric_code": "30009",
    "message": "Provider client is not ready"
  }
}

Another wallet account is being created in this workspace. Wait for it to complete before trying again.

What to do: Keep request_id and the structured codes, and investigate the current operation before taking another action.

{
  "request_id": "req_example",
  "error": {
    "code": "wallet_account_creation_in_progress",
    "numeric_code": "20030",
    "message": "Account creation is in progress; please wait"
  }
}

This idempotency key belongs to different business parameters. Reconcile the original operation before starting another.

What to do: Keep request_id and the structured codes, and investigate the current operation before taking another action.

{
  "request_id": "req_example",
  "error": {
    "code": "wallet_idempotency_conflict",
    "numeric_code": "20024",
    "message": "Idempotency key was used for a different request"
  }
}

The wallet cannot cover this account purchase. The owner can top up, then confirm the original request.

What to do: Keep request_id and the structured codes, and investigate the current operation before taking another action.

{
  "request_id": "req_example",
  "error": {
    "code": "wallet_insufficient_funds",
    "numeric_code": "20023",
    "message": "Insufficient wallet balance"
  }
}

New wallet purchases are disabled; do not assume existing account operations are cancelled.

What to do: Keep request_id and the structured codes, and investigate the current operation before taking another action.

{
  "request_id": "req_example",
  "error": {
    "code": "wallet_workspace_disabled",
    "numeric_code": "20022",
    "message": "New wallet purchases are disabled"
  }
}

The workspace messaging account limit has been reached; check usage and quota.

What to do: Keep request_id and the structured codes, and investigate the current operation before taking another action.

{
  "request_id": "req_example",
  "error": {
    "code": "workspace_account_quota_exceeded",
    "numeric_code": "20014",
    "message": "Workspace account quota exceeded"
  }
}

GET /contacts/info reported Conversation not found. Check the target identifier and the account used for the lookup.

What to do: Check the target identifier, resource ownership and current workspace. Do not treat a confirmed missing or inaccessible target as a temporary service failure to retry automatically.

{
  "request_id": "req_example",
  "error": {
    "code": "contact_not_found",
    "numeric_code": "35000",
    "message": "Conversation not found"
  }
}

Block contact: an unclassified error interrupted this change; the resulting resource state needs confirmation.

What to do: Read the current resource state and confirm the previous outcome before repeating this change. Keep request_id; do not automatically repeat a write whose outcome is unknown.

{
  "request_id": "req_example",
  "error": {
    "code": "block_contact_failed",
    "numeric_code": "35005",
    "message": "Failed to block contact"
  }
}

Calls

The call could not be queried or ended. Check the current operation and call state.

What to do: Query the managed call and its call_id/state before creating or ending another call. Preparing is not dialing or answered; ended and failed are terminal states. A failed state alone is not a reason to repeat hangup.

{
  "request_id": "req_example",
  "error": {
    "code": "call_control_failed",
    "numeric_code": "38004",
    "message": "Failed to control call"
  }
}

Create account: resource creation failed or could not be confirmed.

What to do: List or query existing resources to check whether creation already took effect before creating another. Correct the underlying cause and keep request_id; do not create duplicates automatically.

{
  "request_id": "req_example",
  "error": {
    "code": "create_account_failed",
    "numeric_code": "20002",
    "message": "Failed to create account"
  }
}

Calls

Create a call: resource creation failed or could not be confirmed.

What to do: List or query existing resources to check whether creation already took effect before creating another. Correct the underlying cause and keep request_id; do not create duplicates automatically.

{
  "request_id": "req_example",
  "error": {
    "code": "create_call_failed",
    "numeric_code": "38002",
    "message": "Failed to create call"
  }
}

Add contact: resource creation failed or could not be confirmed.

What to do: List or query existing resources to check whether creation already took effect before creating another. Correct the underlying cause and keep request_id; do not create duplicates automatically.

{
  "request_id": "req_example",
  "error": {
    "code": "create_contact_failed",
    "numeric_code": "35003",
    "message": "Failed to create contact"
  }
}

Create a group: resource creation failed or could not be confirmed.

What to do: List or query existing resources to check whether creation already took effect before creating another. Correct the underlying cause and keep request_id; do not create duplicates automatically.

{
  "request_id": "req_example",
  "error": {
    "code": "create_group_failed",
    "numeric_code": "34002",
    "message": "Failed to create group"
  }
}

Create webhook endpoint: an unclassified error interrupted this change; the resulting resource state needs confirmation.

What to do: Read the endpoint configuration and account scope before resubmitting. PATCH replaces settings; retain the intended subscriptions, signing configuration and retry policy. For an active-endpoint conflict, update the existing endpoint or deactivate it before enabling another.

{
  "request_id": "req_example",
  "error": {
    "code": "create_webhook_endpoint_failed",
    "numeric_code": "40001",
    "message": "Failed to create webhook endpoint"
  }
}

Deactivate webhook endpoint: stopping or deactivation could not be confirmed; preserving the intended stopped state matters.

What to do: Query the current state to confirm whether stopping or deactivation took effect. Do not start or reconnect a resource that you intended to stop.

{
  "request_id": "req_example",
  "error": {
    "code": "deactivate_webhook_endpoint_failed",
    "numeric_code": "40004",
    "message": "Failed to deactivate webhook endpoint"
  }
}

Delete account: the deletion result could not be confirmed.

What to do: Query the resource to determine whether deletion already succeeded, then decide whether another delete is needed. Keep request_id and follow this endpoint’s documented success response.

{
  "request_id": "req_example",
  "error": {
    "code": "delete_account_failed",
    "numeric_code": "20004",
    "message": "Failed to delete account"
  }
}

Delete label: the deletion result could not be confirmed.

What to do: Query the resource to determine whether deletion already succeeded, then decide whether another delete is needed. Keep request_id and follow this endpoint’s documented success response.

{
  "request_id": "req_example",
  "error": {
    "code": "delete_label_failed",
    "numeric_code": "37014",
    "message": "Failed to delete label"
  }
}

Delete webhook endpoint: the deletion result could not be confirmed.

What to do: Query the resource to determine whether deletion already succeeded, then decide whether another delete is needed. Keep request_id and follow this endpoint’s documented success response.

{
  "request_id": "req_example",
  "error": {
    "code": "delete_webhook_endpoint_failed",
    "numeric_code": "40005",
    "message": "Failed to delete webhook endpoint"
  }
}

Edit message: an unclassified error interrupted this change; the resulting resource state needs confirmation.

What to do: Read the current resource state and confirm the previous outcome before repeating this change. Keep request_id; do not automatically repeat a write whose outcome is unknown.

{
  "request_id": "req_example",
  "error": {
    "code": "edit_message_failed",
    "numeric_code": "36005",
    "message": "Failed to edit message"
  }
}

Get account: the service could not produce a valid query result.

What to do: Keep request_id and check the requested identifiers and account access. Retry this read only after checking the cause; a failed query does not prove an empty or missing resource.

{
  "request_id": "req_example",
  "error": {
    "code": "get_account_failed",
    "numeric_code": "20001",
    "message": "Failed to get account"
  }
}

Get authentication state: the service could not produce a valid query result.

What to do: Keep request_id and check the requested identifiers and account access. Retry this read only after checking the cause; a failed query does not prove an empty or missing resource.

{
  "request_id": "req_example",
  "error": {
    "code": "get_auth_state_failed",
    "numeric_code": "20006",
    "message": "Failed to get account auth state"
  }
}

Get contact: the service could not produce a valid query result.

What to do: Keep request_id and check the requested identifiers and account access. Retry this read only after checking the cause; a failed query does not prove an empty or missing resource.

{
  "request_id": "req_example",
  "error": {
    "code": "get_contact_failed",
    "numeric_code": "35002",
    "message": "Failed to get contact"
  }
}

Check contact membership: the service could not produce a valid query result.

What to do: Keep request_id and check the requested identifiers and account access. Retry this read only after checking the cause; a failed query does not prove an empty or missing resource.

{
  "request_id": "req_example",
  "error": {
    "code": "get_contact_membership_failed",
    "numeric_code": "35004",
    "message": "Failed to get contact membership"
  }
}

Get conversation: the service could not produce a valid query result.

What to do: Keep request_id and check the requested identifiers and account access. Retry this read only after checking the cause; a failed query does not prove an empty or missing resource.

{
  "request_id": "req_example",
  "error": {
    "code": "get_conversation_failed",
    "numeric_code": "37004",
    "message": "Failed to get conversation"
  }
}

Get group details: the service could not produce a valid query result.

What to do: Keep request_id and check the requested identifiers and account access. Retry this read only after checking the cause; a failed query does not prove an empty or missing resource.

{
  "request_id": "req_example",
  "error": {
    "code": "get_group_failed",
    "numeric_code": "34001",
    "message": "Failed to get group"
  }
}

Get group invite link: the service could not produce a valid query result.

What to do: Keep request_id and check the requested identifiers and account access. Retry this read only after checking the cause; a failed query does not prove an empty or missing resource.

{
  "request_id": "req_example",
  "error": {
    "code": "get_group_invite_code_failed",
    "numeric_code": "34010",
    "message": "Failed to get group invite code"
  }
}

Read the current account session: the service could not load the current session.

What to do: Keep request_id and check the requested identifiers and account access. Retry this read only after checking the cause; a failed query does not prove an empty or missing resource.

{
  "request_id": "req_example",
  "error": {
    "code": "get_session_failed",
    "numeric_code": "20005",
    "message": "Failed to get account session"
  }
}

Get webhook endpoint: the service could not produce a valid query result.

What to do: Keep request_id and check the requested identifiers and account access. Retry this read only after checking the cause; a failed query does not prove an empty or missing resource.

{
  "request_id": "req_example",
  "error": {
    "code": "get_webhook_endpoint_failed",
    "numeric_code": "40002",
    "message": "Failed to get webhook endpoint"
  }
}

Get current workspace: the service could not produce a valid query result.

What to do: Keep request_id and check the requested identifiers and account access. Retry this read only after checking the cause; a failed query does not prove an empty or missing resource.

{
  "request_id": "req_example",
  "error": {
    "code": "get_workspace_failed",
    "numeric_code": "41000",
    "message": "Failed to get workspace"
  }
}

Leave a group: an unclassified error interrupted this change; the resulting resource state needs confirmation.

What to do: Read the current resource state and confirm the previous outcome before repeating this change. Keep request_id; do not automatically repeat a write whose outcome is unknown.

{
  "request_id": "req_example",
  "error": {
    "code": "leave_group_failed",
    "numeric_code": "34003",
    "message": "Failed to leave group"
  }
}

List accounts: the service could not produce a valid query result.

What to do: Keep request_id and check the requested identifiers and account access. Retry this read only after checking the cause; a failed query does not prove an empty or missing resource.

{
  "request_id": "req_example",
  "error": {
    "code": "list_accounts_failed",
    "numeric_code": "20000",
    "message": "Failed to list accounts"
  }
}

List API keys: the service could not produce a valid query result.

What to do: Keep request_id and check the requested identifiers and account access. Retry this read only after checking the cause; a failed query does not prove an empty or missing resource.

{
  "request_id": "req_example",
  "error": {
    "code": "list_api_keys_failed",
    "numeric_code": "11100",
    "message": "Failed to list API keys"
  }
}

Get blocklist: the service could not produce a valid query result.

What to do: Keep request_id and check the requested identifiers and account access. Retry this read only after checking the cause; a failed query does not prove an empty or missing resource.

{
  "request_id": "req_example",
  "error": {
    "code": "list_blocklist_failed",
    "numeric_code": "35007",
    "message": "Failed to list blocklist"
  }
}

List contacts: the service could not produce a valid query result.

What to do: Keep request_id and check the requested identifiers and account access. Retry this read only after checking the cause; a failed query does not prove an empty or missing resource.

{
  "request_id": "req_example",
  "error": {
    "code": "list_contacts_failed",
    "numeric_code": "35001",
    "message": "Failed to list contacts"
  }
}

List conversation labels: the service could not produce a valid query result.

What to do: Keep request_id and check the requested identifiers and account access. Retry this read only after checking the cause; a failed query does not prove an empty or missing resource.

{
  "request_id": "req_example",
  "error": {
    "code": "list_conversation_labels_failed",
    "numeric_code": "37012",
    "message": "Failed to list conversation labels"
  }
}

List conversation members: the service could not produce a valid query result.

What to do: Keep request_id and check the requested identifiers and account access. Retry this read only after checking the cause; a failed query does not prove an empty or missing resource.

{
  "request_id": "req_example",
  "error": {
    "code": "list_conversation_members_failed",
    "numeric_code": "37005",
    "message": "Failed to list conversation members"
  }
}

List conversations: the service could not produce a valid query result.

What to do: Keep request_id and check the requested identifiers and account access. Retry this read only after checking the cause; a failed query does not prove an empty or missing resource.

{
  "request_id": "req_example",
  "error": {
    "code": "list_conversations_failed",
    "numeric_code": "37003",
    "message": "Failed to list conversations"
  }
}

List group join requests: the service could not produce a valid query result.

What to do: Keep request_id and check the requested identifiers and account access. Retry this read only after checking the cause; a failed query does not prove an empty or missing resource.

{
  "request_id": "req_example",
  "error": {
    "code": "list_group_join_requests_failed",
    "numeric_code": "34007",
    "message": "Failed to list group join requests"
  }
}

List groups: the service could not produce a valid query result.

What to do: Keep request_id and check the requested identifiers and account access. Retry this read only after checking the cause; a failed query does not prove an empty or missing resource.

{
  "request_id": "req_example",
  "error": {
    "code": "list_groups_failed",
    "numeric_code": "34000",
    "message": "Failed to list groups"
  }
}

List provider regions: the service could not produce a valid query result.

What to do: Keep request_id and check the requested identifiers and account access. Retry this read only after checking the cause; a failed query does not prove an empty or missing resource.

{
  "request_id": "req_example",
  "error": {
    "code": "list_provider_regions_failed",
    "numeric_code": "30011",
    "message": "Failed to list provider regions"
  }
}

List webhook endpoints: the service could not produce a valid query result.

What to do: Keep request_id and check the requested identifiers and account access. Retry this read only after checking the cause; a failed query does not prove an empty or missing resource.

{
  "request_id": "req_example",
  "error": {
    "code": "list_webhook_endpoints_failed",
    "numeric_code": "40000",
    "message": "Failed to list webhook endpoints"
  }
}

Mark a conversation as read: an unclassified error interrupted this change; the resulting resource state needs confirmation.

What to do: Read the current resource state and confirm the previous outcome before repeating this change. Keep request_id; do not automatically repeat a write whose outcome is unknown.

{
  "request_id": "req_example",
  "error": {
    "code": "mark_conversation_read_failed",
    "numeric_code": "37006",
    "message": "Failed to mark conversation as read"
  }
}

Mark a conversation as unread: an unclassified error interrupted this change; the resulting resource state needs confirmation.

What to do: Read the current resource state and confirm the previous outcome before repeating this change. Keep request_id; do not automatically repeat a write whose outcome is unknown.

{
  "request_id": "req_example",
  "error": {
    "code": "mark_conversation_unread_failed",
    "numeric_code": "37007",
    "message": "Failed to mark conversation as unread"
  }
}

Mute conversation notifications: an unclassified error interrupted this change; the resulting resource state needs confirmation.

What to do: Read the current resource state and confirm the previous outcome before repeating this change. Keep request_id; do not automatically repeat a write whose outcome is unknown.

{
  "request_id": "req_example",
  "error": {
    "code": "mute_conversation_failed",
    "numeric_code": "37008",
    "message": "Failed to mute conversation"
  }
}

Pin conversation: an unclassified error interrupted this change; the resulting resource state needs confirmation.

What to do: Read the current resource state and confirm the previous outcome before repeating this change. Keep request_id; do not automatically repeat a write whose outcome is unknown.

{
  "request_id": "req_example",
  "error": {
    "code": "pin_conversation_failed",
    "numeric_code": "37010",
    "message": "Failed to pin conversation"
  }
}

Pin / unpin message: an unclassified error interrupted this change; the resulting resource state needs confirmation.

What to do: Read the current resource state and confirm the previous outcome before repeating this change. Keep request_id; do not automatically repeat a write whose outcome is unknown.

{
  "request_id": "req_example",
  "error": {
    "code": "pin_message_failed",
    "numeric_code": "36002",
    "message": "Failed to pin message"
  }
}

React to message: an unclassified error interrupted this change; the resulting resource state needs confirmation.

What to do: Read the current resource state and confirm the previous outcome before repeating this change. Keep request_id; do not automatically repeat a write whose outcome is unknown.

{
  "request_id": "req_example",
  "error": {
    "code": "react_message_failed",
    "numeric_code": "36004",
    "message": "Failed to react to message"
  }
}

Request conversation history: an unclassified error interrupted this change; the resulting resource state needs confirmation.

What to do: Check the WhatsApp private conversation and before anchor. Keep request_id for HTTP diagnosis only. History events may arrive after an HTTP timeout; do not retry automatically or treat no event, an empty batch or a short batch as completion.

{
  "request_id": "req_example",
  "error": {
    "code": "request_conversation_history_failed",
    "numeric_code": "37016",
    "message": "Failed to request conversation history"
  }
}

Revoke message: an unclassified error interrupted this change; the resulting resource state needs confirmation.

What to do: Read the current resource state and confirm the previous outcome before repeating this change. Keep request_id; do not automatically repeat a write whose outcome is unknown.

{
  "request_id": "req_example",
  "error": {
    "code": "revoke_message_failed",
    "numeric_code": "36003",
    "message": "Failed to revoke message"
  }
}

Run an account action: an unclassified error interrupted this change; the resulting resource state needs confirmation.

What to do: Read the current resource state and confirm the previous outcome before repeating this change. Keep request_id; do not automatically repeat a write whose outcome is unknown.

{
  "request_id": "req_example",
  "error": {
    "code": "run_action_failed",
    "numeric_code": "20007",
    "message": "Failed to run account action"
  }
}

Run an authorization action: the authorization action failed; check the existing flow rather than assuming authorization must restart.

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.

{
  "request_id": "req_example",
  "error": {
    "code": "run_auth_action_failed",
    "numeric_code": "20010",
    "message": "Failed to run auth action"
  }
}

Change runtime state: the runtime action failed; this response alone does not establish the final connection state.

What to do: Query authorization and runtime status, then choose refresh, start or reconnect only when appropriate for the intended state and channel. A connection problem alone does not prove logout. Confirm running before dependent business operations.

{
  "request_id": "req_example",
  "error": {
    "code": "run_runtime_action_failed",
    "numeric_code": "20008",
    "message": "Failed to run runtime action"
  }
}

Run a session action: the authorization action failed; check the existing flow rather than assuming authorization must restart.

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.

{
  "request_id": "req_example",
  "error": {
    "code": "run_session_action_failed",
    "numeric_code": "20009",
    "message": "Failed to run session action"
  }
}

Message sending failed or its result could not be confirmed.

What to do: Confirm whether the original message or reply was created before sending again. A timeout or failed response can leave the outcome unknown; a later query with no matching reply does not prove nothing was written. Do not automatically resend.

{
  "request_id": "req_example",
  "error": {
    "code": "send_message_failed",
    "numeric_code": "36001",
    "message": "Failed to send message"
  }
}

Set contact note: an unclassified error interrupted this change; the resulting resource state needs confirmation.

What to do: Read the current resource state and confirm the previous outcome before repeating this change. Keep request_id; do not automatically repeat a write whose outcome is unknown.

{
  "request_id": "req_example",
  "error": {
    "code": "set_contact_note_failed",
    "numeric_code": "35008",
    "message": "Failed to set contact note"
  }
}

Set group join approval mode: the group change failed; channel rejection or missing administrator permission may be involved.

What to do: Check the group, current membership, the required administrator permission and the current result. Resolve access or permission issues before repeating the change; an unknown write result must be reconciled first.

{
  "request_id": "req_example",
  "error": {
    "code": "set_group_join_approval_mode_failed",
    "numeric_code": "34009",
    "message": "Failed to set group join approval mode"
  }
}

Add / remove label on conversations: an unclassified error interrupted this change; the resulting resource state needs confirmation.

What to do: Read the current resource state and confirm the previous outcome before repeating this change. Keep request_id; do not automatically repeat a write whose outcome is unknown.

{
  "request_id": "req_example",
  "error": {
    "code": "set_label_members_failed",
    "numeric_code": "37015",
    "message": "Failed to set label members"
  }
}

Unblock contact: an unclassified error interrupted this change; the resulting resource state needs confirmation.

What to do: Read the current resource state and confirm the previous outcome before repeating this change. Keep request_id; do not automatically repeat a write whose outcome is unknown.

{
  "request_id": "req_example",
  "error": {
    "code": "unblock_contact_failed",
    "numeric_code": "35006",
    "message": "Failed to unblock contact"
  }
}

Enable conversation notifications: an unclassified error interrupted this change; the resulting resource state needs confirmation.

What to do: Read the current resource state and confirm the previous outcome before repeating this change. Keep request_id; do not automatically repeat a write whose outcome is unknown.

{
  "request_id": "req_example",
  "error": {
    "code": "unmute_conversation_failed",
    "numeric_code": "37009",
    "message": "Failed to unmute conversation"
  }
}

Unpin conversation: an unclassified error interrupted this change; the resulting resource state needs confirmation.

What to do: Read the current resource state and confirm the previous outcome before repeating this change. Keep request_id; do not automatically repeat a write whose outcome is unknown.

{
  "request_id": "req_example",
  "error": {
    "code": "unpin_conversation_failed",
    "numeric_code": "37011",
    "message": "Failed to unpin conversation"
  }
}

Update account: an unclassified error interrupted this change; the resulting resource state needs confirmation.

What to do: Read the current resource state and confirm the previous outcome before repeating this change. Keep request_id; do not automatically repeat a write whose outcome is unknown.

{
  "request_id": "req_example",
  "error": {
    "code": "update_account_failed",
    "numeric_code": "20003",
    "message": "Failed to update account"
  }
}

Update group info: the group change failed; channel rejection or missing administrator permission may be involved.

What to do: Check the group, current membership, the required administrator permission and the current result. Resolve access or permission issues before repeating the change; an unknown write result must be reconciled first.

{
  "request_id": "req_example",
  "error": {
    "code": "update_group_info_failed",
    "numeric_code": "34006",
    "message": "Failed to update group info"
  }
}

Approve / reject join requests: the group change failed; channel rejection or missing administrator permission may be involved.

What to do: Check the group, current membership, the required administrator permission and the current result. Resolve access or permission issues before repeating the change; an unknown write result must be reconciled first.

{
  "request_id": "req_example",
  "error": {
    "code": "update_group_join_requests_failed",
    "numeric_code": "34008",
    "message": "Failed to update group join requests"
  }
}

Update group members: the group change failed; channel rejection or missing administrator permission may be involved.

What to do: Check the group, current membership, the required administrator permission and the current result. Resolve access or permission issues before repeating the change; an unknown write result must be reconciled first.

{
  "request_id": "req_example",
  "error": {
    "code": "update_group_members_failed",
    "numeric_code": "34005",
    "message": "Failed to update group members"
  }
}

Update webhook endpoint: an unclassified error interrupted this change; the resulting resource state needs confirmation.

What to do: Read the endpoint configuration and account scope before resubmitting. PATCH replaces settings; retain the intended subscriptions, signing configuration and retry policy. For an active-endpoint conflict, update the existing endpoint or deactivate it before enabling another.

{
  "request_id": "req_example",
  "error": {
    "code": "update_webhook_endpoint_failed",
    "numeric_code": "40003",
    "message": "Failed to update webhook endpoint"
  }
}

Create or update label: an unclassified error interrupted this change; the resulting resource state needs confirmation.

What to do: Read the current resource state and confirm the previous outcome before repeating this change. Keep request_id; do not automatically repeat a write whose outcome is unknown.

{
  "request_id": "req_example",
  "error": {
    "code": "upsert_label_failed",
    "numeric_code": "37013",
    "message": "Failed to upsert label"
  }
}

The channel does not support this operation; choose a supported operation.

What to do: Use a channel and action listed as supported. Repeating the same request does not add capabilities or grant beta access.

{
  "request_id": "req_example",
  "error": {
    "code": "unsupported_by_provider",
    "numeric_code": "30003",
    "message": "Operation not supported by this provider"
  }
}

Posts & Comments

Get account post: the service could not produce a valid query result.

What to do: Keep request_id and check the requested identifiers and account access. Retry this read only after checking the cause; a failed query does not prove an empty or missing resource.

{
  "request_id": "req_example",
  "error": {
    "code": "get_post_failed",
    "numeric_code": "39006",
    "message": "Failed to get post"
  }
}

Posts & Comments

List top-level post comments: the service could not produce a valid query result.

What to do: Keep request_id and check the requested identifiers and account access. Retry this read only after checking the cause; a failed query does not prove an empty or missing resource.

{
  "request_id": "req_example",
  "error": {
    "code": "list_post_comments_failed",
    "numeric_code": "39003",
    "message": "Failed to list post comments"
  }
}

Posts & Comments

List account posts: the service could not produce a valid query result.

What to do: Keep request_id and check the requested identifiers and account access. Retry this read only after checking the cause; a failed query does not prove an empty or missing resource.

{
  "request_id": "req_example",
  "error": {
    "code": "list_posts_failed",
    "numeric_code": "39002",
    "message": "Failed to list posts"
  }
}

The channel service is unavailable. Check status or try again later; confirm the result before retrying writes.

What to do: Keep request_id and the structured codes, and investigate the current operation before taking another action.

{
  "request_id": "req_example",
  "error": {
    "code": "provider_adapter_not_found",
    "numeric_code": "30004",
    "message": "Provider adapter unavailable"
  }
}

The channel service is unavailable. Check status or try again later; confirm the result before retrying writes.

What to do: Keep request_id and the structured codes, and investigate the current operation before taking another action.

{
  "request_id": "req_example",
  "error": {
    "code": "provider_unavailable",
    "numeric_code": "30002",
    "message": "Provider service unavailable"
  }
}

Posts & Comments

Check the post, confirmed top-level comment and error classification. If the write outcome is unknown, keep request_id and investigate before any resend; absence in a later read is not enough to justify retrying.

What to do: Confirm whether the original message or reply was created before sending again. A timeout or failed response can leave the outcome unknown; a later query with no matching reply does not prove nothing was written. Do not automatically resend.

{
  "request_id": "req_example",
  "error": {
    "code": "reply_post_comment_failed",
    "numeric_code": "39004",
    "message": "Failed to confirm comment reply; result may be unknown, do not automatically retry"
  }
}

Account allocation is temporarily unavailable; retry shortly.

What to do: Keep request_id and the structured codes, and investigate the current operation before taking another action.

{
  "request_id": "req_example",
  "error": {
    "code": "allocation_service_unavailable",
    "numeric_code": "20012",
    "message": "Allocation service is temporarily unavailable"
  }
}

Calls

The calling service is unavailable. Check the Provider/Gateway connection and configuration.

What to do: Query the managed call and its call_id/state before creating or ending another call. Preparing is not dialing or answered; ended and failed are terminal states. A failed state alone is not a reason to repeat hangup.

{
  "request_id": "req_example",
  "error": {
    "code": "call_service_unavailable",
    "numeric_code": "38001",
    "message": "Call service unavailable"
  }
}

The authorization-session service is unavailable or not configured for this request. Contact the service operator to check the authorization-session service.

What to do: Keep request_id and the structured codes, and investigate the current operation before taking another action.

{
  "request_id": "req_example",
  "error": {
    "code": "internal_auth_not_configured",
    "numeric_code": "11006",
    "message": "Internal endpoint authentication is not configured"
  }
}

Wallet data or configuration is temporarily unavailable. A failed write can have an unknown result; reconcile the original operation.

What to do: Read the current resource state and confirm the previous outcome before repeating this change. Keep request_id; do not automatically repeat a write whose outcome is unknown.

{
  "request_id": "req_example",
  "error": {
    "code": "wallet_unavailable",
    "numeric_code": "20028",
    "message": "Wallet service is unavailable"
  }
}

The provider could not complete the operation. message can include the original cause after “Provider operation failed:”; the reason text varies and is not a stable program interface.

What to do: Query the resource to determine whether deletion already succeeded, then decide whether another delete is needed. Keep request_id and follow this endpoint’s documented success response.

Provider operation failed

The provider instance needed by this account is missing. This is a runtime availability problem, not proof that authorization expired.

What to do: Query authorization and runtime status, then choose refresh, start or reconnect only when appropriate for the intended state and channel. A connection problem alone does not prove logout. Confirm running before dependent business operations.

Provider instance is missing

The provider runtime is stopped. Confirm whether that is intentional before starting it; a stopped runtime does not itself mean logout.

What to do: Query authorization and runtime status, then choose refresh, start or reconnect only when appropriate for the intended state and channel. A connection problem alone does not prove logout. Confirm running before dependent business operations.

Provider runtime is stopped

The provider explicitly rejected the submitted authentication code. Check the channel’s code flow and expiry. Existing paths may use 30001 instead of the contract’s 30016.

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.

Provider rejected the authentication code

The upstream channel explicitly rejected excessive request frequency. This numeric classification preserves the operation’s existing HTTP status and code.

What to do: Pause requests and retry later within a bounded policy. No fixed delay or Retry-After handling is guaranteed here. Confirm the previous result before retrying a write.

Provider rate limit exceeded

The account’s provider App State baseline is out of sync. This is an account synchronization condition, not a generic request-format error.

What to do: Wait for the provider to restore the account’s App State baseline, then check current state before retrying. Do not infer that credentials are invalid or begin reauthorization solely from this classification.

Provider app state is out of sync

The platform explicitly restricted this message send: HTTP 502, provider_unavailable, 30019. This does not establish a permanent account ban or a fixed time when sending will be allowed again.

What to do: Stop automatic retries for this message restriction. Resume sending only after the platform restriction is confirmed lifted; there is no fixed release time, and this error alone does not require reauthorization.

Message sending is restricted by the platform

A synchronous request using whatsapp-protocol identified an account login restriction with numeric_code=30020. This can affect session import, runtime, sending and contact queries while retaining the current operation’s HTTP status and code. Do not substitute the WhatsApp 20102 event contract for this channel.

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.

Account login is restricted. Check the official WhatsApp app for details.

WhatsApp was not connected when this operation ran. The original connection message is retained. This does not prove logout or expired authorization and does not automatically reconnect, resend or change account state.

What to do: Pause operations that require the connection. First call POST /v1/accounts/{account_id}/runtime/refresh, recover according to the latest state and confirm runtime_status=running before business requests. Confirm the previous write result before resending.

Account is not connected to the messaging platform

The group was not found under this account; check the group ID.

What to do: Check the target identifier, resource ownership and current workspace. Do not treat a confirmed missing or inaccessible target as a temporary service failure to retry automatically.

Group not found

The group may exist, but this account is not a participant. For WhatsApp conversation details, 404 conversation_not_found / 34011 means the group is not visible to this account; it is not a temporary gateway failure.

What to do: Check the target identifier, resource ownership and current workspace. Do not treat a confirmed missing or inaccessible target as a temporary service failure to retry automatically.

Account is not participating in this group

WhatsApp requires group administrator privileges to send this message. Adjust the account's group role before retrying.

What to do: Keep request_id and the structured codes, and investigate the current operation before taking another action.

Group administrator privileges are required to send messages to this group

Sticker media failed validation before the provider send. The response may give a specific preparation reason; numeric_code=36007 does not mean a send was attempted.

What to do: Fix the reported sticker media issue before sending again. This classification is returned during media preparation before the provider send; it must not be presented as an unknown completed send.

Invalid sticker media

The target API key was not found in this workspace. Key update and rotation preserve HTTP 400 and their original update_api_key_failed or rotate_api_key_failed code; 11104 refines the cause.

What to do: Check the target key under the current workspace before changing or rotating it. A missing target is not repaired by retrying. After an unknown rotation result, confirm which credentials remain usable without exposing key material.

API key not found

The target webhook endpoint was not found in this scope. GET, PATCH and deactivate keep their operation-specific code and HTTP 500, with numeric_code=40006. This detail does not apply to the idempotent DELETE, which returns 204 for an absent endpoint.

What to do: Check the target identifier, resource ownership and current workspace. Do not treat a confirmed missing or inaccessible target as a temporary service failure to retry automatically.

Webhook endpoint not found

WhatsApp synchronous message sending identified an account login restriction: HTTP 502, provider_unavailable, 20102. The same numeric meaning can appear as account_restricted in a WhatsApp failure event; the HTTP response does not itself update account state or create an extra event.

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.

Account login is restricted. Check the official WhatsApp app for details.

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.

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

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.

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

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.

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