Common Errors & Troubleshooting

1. Coexistence Errors

WhatsApp Channel Shows Not Connected

This issue usually occurs when the WhatsApp channel fails to establish a proper connection due to incomplete verification or account restrictions.

Possible Causes

• Meta Business Account is under review or disconnected

• Business verification is incomplete

• Coexistence policy validation failed

Resolution

• Complete Business Verification from https://business.facebook.com/settings under Security Center

• Ensure business details match submitted documents

• Check account quality in https://business.facebook.com/accountquality

• Contact support if the issue persists

You can visit the Business Verification and Check Account Quality sections to understand how to complete these steps.

Coexistence Gets Auto-Disconnected

This happens when Meta automatically disconnects the channel due to policy or quality issues.

Possible Causes

• Policy violations

• Poor quality rating

• Interrupted signup

• Session timeout

Resolution

• Review account quality in https://business.facebook.com/accountquality

• Ensure account status is approved before reconnecting

You can visit the Check Account Quality section to learn how to verify and resolve issues.

Embedded Signup Shows Successful but Not Fully Connected

Even if signup appears successful, backend onboarding may remain incomplete, causing messaging to fail.

Possible Causes

• Signup shows successful

• WhatsApp Business app shows connected

• Meta shows pending

• Messaging not working

Resolution

• Re-register the number from https://business.facebook.com/wa/manage/phone-numbers

• Ensure all steps complete without interruption

You can visit the Retry Onboarding section for detailed steps.

Login Succeeds but Channel Disconnects Later

This is usually related to browser or session issues rather than account configuration.

Possible Causes

• Cache or cookies issues

• Pop-ups blocked

• Session expired

Resolution

• Use a supported browser (Chrome recommended)

• Enable pop-ups

• Retry onboarding from https://business.facebook.com/wa/manage

• Clear browser cache before retrying

You can visit the Retry Onboarding section for step-by-step guidance.

2. New Number connection Errors

Channel Status Shows Pending

This indicates that Meta onboarding is still in progress or verification is incomplete.

Possible Causes

• Business verification pending

• Backend registration incomplete

• Account under review

Resolution

• Complete verification via https://business.facebook.com/settings

• Wait up to 24 hours for Meta processing

• Retry onboarding if status does not update

You can visit the Business Verification section to complete the process.

Channel Connection Fails During Setup

This occurs when onboarding is interrupted or required steps are not completed.

Possible Causes

• Verification incomplete

• Signup interrupted

Resolution

• Complete business verification from https://business.facebook.com/settings

• Retry onboarding via https://business.facebook.com/wa/manage/phone-numbers

You can visit the Business Verification and Retry Onboarding sections for guidance.

OTP Not Received

OTP issues are generally caused by formatting errors or telecom restrictions.

Possible Causes

• Incorrect number format

• OTP delay or block

Resolution

• Enter number without "+" or spaces

• Retry using SMS or voice option in https://business.facebook.com/wa/manage/phone-numbers

• Check DND/SMS blocking with telecom provider

You can visit the OTP Troubleshooting section for more details.

Number Verification Fails

This happens when the number is already linked to a WhatsApp account.

Possible Causes

• Number linked to WhatsApp app

• Not eligible for API

Resolution

• Delete the WhatsApp account from mobile

• Wait 24–48 hours before retrying

You can visit the Remove Number from WhatsApp section to understand the steps.

Number Already in Use

This indicates that the number is actively associated with another WhatsApp account.

Possible Causes

• Active WhatsApp Personal/Business account

Resolution

• Delete existing WhatsApp account

• Retry after 24–48 hours

You can visit the Remove Number from WhatsApp section for detailed steps.

3. Common Errors

Number Already Connected with Another Partner

This occurs when the number is already linked to another BSP.

Possible Causes

• Existing partner integration

• Number previously onboarded elsewhere

Resolution

• Go to https://business.facebook.com/settings → Accounts → WhatsApp Accounts

• Open the Partners section and remove the existing partner

• If using coexistence, disconnect from WhatsApp Business app

• Retry onboarding

You can visit the Remove Existing Partner and Remove Partner from WhatsApp Business App sections to complete this process.

4. Meta Errors

Business Does Not Meet Policy Requirements

This error indicates non-compliance with WhatsApp policies.

Resolution

• Ensure website is live and publicly accessible

• Verify business details are accurate

• Submit review via https://business.facebook.com/business/help

You can visit the Request Review section to understand how to raise an appeal.

Currency Mismatch in WABA

This happens when the payment method currency differs from the WABA currency.

Resolution

• Create a new WABA from https://business.facebook.com/wa/manage

You can visit the Create / Access WABA section for detailed steps.

Security PIN Mismatch (2FA Issue)

This occurs when an incorrect PIN is entered.

Resolution

• Use correct PIN or reset 2FA via https://business.facebook.com/wa/manage

You can visit the Create / Access WABA section for guidance.

Unsupported Post Request

This is usually a temporary onboarding issue.

Resolution

• Retry onboarding via https://business.facebook.com/wa/manage/phone-numbers

• Create new WABA if issue persists

You can visit the Retry Onboarding section for steps.

WABA Limit Exceeded

Meta limits the number of WABAs per Business Manager.

Resolution

• Delete unused WABAs or create a new Business Manager via https://business.facebook.com/wa/manage

You can visit the Create / Access WABA section for more details.

WABA Temporarily Banned / Permanently Disabled

This occurs due to policy violations or poor quality rating.

Resolution

• Check status in https://business.facebook.com/accountquality

• Request review via https://business.facebook.com/business/help

• Create new WABA if permanently disabled

You can visit the Check Account Quality and Request Review sections to proceed.

Business Restricted

This is usually due to invalid or non-compliant website details.

Resolution

• Submit review request via https://business.facebook.com/business/help

You can visit the Request Review section for guidance