Setup Errors & Solutions

Overview

Setting up a WhatsApp Business Account using the Chakra Chat Embedded Signup (ES) flow. However, users do face errors during the process and need assistance to fix them immediately.

WhatsApp API Setup: Common Errors and Their Resolution

Error 1: Phone isn't eligible

Error message: Your phone number isn't eligible to connect to the WhatsApp Business Platform. More activity on the WhatsApp Business App is needed to help determine eligibility.
Cause: Meta requires the phone number to have been actively used on the WhatsApp Business App for at least 7 days to establish credibility. New or recently registered numbers may not meet eligibility criteria.
Solution: Actively use the WhatsApp Business App for at least 4-7 days to establish messaging history and credibility. Engage in regular communication with customers to demonstrate consistent usage. Do the Following Actions:
Send messages to new numbers (7-10 numbers)
Reply to incoming messages from new numbers
Save numbers as contacts.

Error 2: Phone registered to existing WhatsApp

Error message: This number is registered to an existing WhatsApp account. To use this number, disconnect it from the existing account. Then, return to this page and re-enter the number.
Cause: Meta restricts the immediate reuse of a phone number previously registered with a WABA account. A cooldown period of 1–2 months is required to re-establish the number’s eligibility in the WhatsApp Business App.
Resolution: If the phone number was previously used for a WABA, delete the WABA account via the provider’s platform or from the WhatsApp Manager. Download the WhatsApp Business App, sign up with the same number, and use it actively for 1–2 months to build credibility.

Error 3: Facebook API is not initialized

Error message: Facebook API is not initialized
Cause: This is a temporary issue during the launch of the embedded signup flow
Resolution: Do a hard refresh, Windows (Ctrl + F5) or macOS (Shift + Command + R) and try clicking on Continue with Facebook

Error 4: Portfolio Limit reached

Error Message: You have reached the limit for the number of Businesses you can create at this time.
Cause: There is a limit to the number of Business Accounts that you can create.
Solution: Please use an existing Business Account.

Error 5: Maximum Allowed Phone Linked

Error Message: You have already linked the maximum number of phone numbers allowed for this Business Account. Delete a phone number to continue or request additional numbers.
Cause: The default cap is of 2, and this scale upto 20 numbers over time. Adding number more than the meta authorized cap or the maximum limit can lead to this error.
Solution: Delete an existing number and then add a new number OR use an existing number OR wait for your limit cap to be increase if below 20

Error 6: Display Name Rejected

Error Message: This WhatsApp Business account can't use Current Display Name as its display name because it violates WhatsApp's Display Name Guidelines. Review the guidelines and submit a new name.
Cause: The submitted business display name violates WhatsApp's guidelines ( doesn’t match the business, contains emojis, is too generic.
Solution: Review WhatsApp’s Display Name Guidelines and adjust the name to match the registered business name or website. Enter a new display name and submit again.

Error 7: Error While Pairing Cloud API

Error Message: : Error While Pairing Cloud API during WhatsApp Coexistence Setup in the Emebedded Signup (ES) flow.
Cause: The most likely cause is that your WhatsApp Business number was restricted recently by Meta.(Offical Error documentation awaited from meta).
Solution: It is suggested to wait for the restriction on your WhatsApp business number to be removed and then try the WhatsApp Coexistence setup in Chakra again.

Error message : The business is already sharing this WhatsApp Business account with a partner. Switching partners is not supported in this flow. Disconnect the current partner in the WhatsApp Business app, then return here to connect a new partner.

Cause: This case occurs if you have previously connected your WhatsApp Business Number with a BSP and now attempting to migrate the same number to Chakra Chat. Due to the credit line associated with previous Coexistence BSP still linked to the number, the registration fails.

Solution 1: Reset your WhatsApp Business App account. Use guide - https://chakrahq.com/help/learning-centre/whatsapp-business/reset-whatsapp-business-app

Solution 2: Convert to WhatsApp personal app account, convert it back to WhatsApp Business

Save anything you need first. Export or back up recent customer conversations from the old provider before disconnecting, since chat history won't carry over automatically.
Remove the number from Coexistence. Open the WhatsApp Business App and disconnect the business account from its current API partner.
Switch to the WhatsApp Personal App. Log the number back in there — this step effectively clears the old business/API linkage.
Re-add it as a business account. Reconnect the number within the WhatsApp Business App as normal.
Restart onboarding in Chakra. Go through the Coexistence setup flow again from your Chakra account. Because the number is starting fresh, it'll generate a new WABA ID that isn't tied to the old credit line.

Error 9: Fixing the "WABA Already Has a Payment Method" Error During Coexistence Setup

Exact Error:

In short: the number's billing history is anchored to its old WABA, and Chakra can't inherit it.

When you'll run into this

This shows up specifically if your number was already onboarded to Coexistence through a different platform before you tried connecting it to Chakra. A handful of common cases:

You previously ran Coexistence through another BSP and are now migrating to Chakra.
A teammate or agency set this number up elsewhere in the past, possibly without your knowledge.
The number was part of a Coexistence trial or pilot on a different tool.

How to resolve it?

Since the credit line can't be transferred directly, the fix is to reset the WABA so a fresh one gets created — then Chakra can attach to it cleanly. Here's the sequence:

Solution 1: Reset your WhatsApp Business App account. Use guide - https://chakrahq.com/help/learning-centre/whatsapp-business/reset-whatsapp-business-app

Solution 2: Convert to WhatsApp personal app account, convert it back to WhatsApp Business

Save anything you need first. Export or back up recent customer conversations from the old provider before disconnecting, since chat history won't carry over automatically.
Remove the number from Coexistence. Open the WhatsApp Business App and disconnect the business account from its current API partner.
Switch to the WhatsApp Personal App. Log the number back in there — this step effectively clears the old business/API linkage.
Re-add it as a business account. Reconnect the number within the WhatsApp Business App as normal.
Restart onboarding in Chakra. Go through the Coexistence setup flow again from your Chakra account. Because the number is starting fresh, it'll generate a new WABA ID that isn't tied to the old credit line.

Once this is done, the connection to Chakra should complete without the payment-method error.

Worth knowing!

This limitation applies to every platform offering Coexistence — it's a Meta-level rule, not something specific to how Chakra is built.
Expect a short gap in message visibility while you disconnect and reconnect; this is normal and resolves once the new WABA finishes syncing with Chakra.

Where to Meta documentation for this error?

Meta documents this credit-line behavior in their partner-switching guidance, which covers what happens to existing lines of credit when a business moves between solution providers: Meta — Switching Partners and Line of Credit