Common errors and FAQ's
This guide covers common errors you may encounter when onboarding with the WhatsApp Business API using the embedded signup method, accessing the Business Portfolio, migrating accounts, managing messaging limits, and addressing account/template quality issues.
1. Error: "Business Verification Failed"
Description: Occurs when your business information does not match or fails verification.
Solution:
Ensure the business name, address, and other details match exactly with official documents (e.g., business license, tax document).
Verify that your business is eligible for WhatsApp Business API (e.g., not in restricted categories like gambling or adult content).
Resubmit documents if needed or contact WhatsApp support for further guidance.
2. Error: "Phone Number Already in Use"
Description: The phone number you're trying to register is already associated with another WhatsApp Business account.
Solution:
Confirm if the phone number is linked to another WhatsApp Business or personal account. If so, unlink it before proceeding.
If you’re unsure, reach out to WhatsApp support to check the status of the number.
3. Error: "Business Portfolio Access Denied"
Description: Access to the Business Portfolio is denied, which can occur if permissions are not properly set up.
Solution:
Make sure your Facebook Business Manager account has the required permissions to manage the Business Portfolio. Admin access is necessary.
Verify that the WhatsApp Business Account is correctly linked to the Business Portfolio in your Facebook Business Manager settings.
Check if the Business Manager account has been verified; incomplete verification may cause access issues.
4. Error: "Invalid Business Portfolio ID"
Description: The ID provided for the Business Portfolio is incorrect or not recognized.
Solution:
Double-check the Business Portfolio ID in your Facebook Business Manager under “Account Quality” or “Business Settings.”
Ensure that your WhatsApp Business API account is linked to this specific Business Portfolio.
If needed, log out and log back in to refresh the connection and try again.
5. Error: "Portfolio Configuration Incomplete"
Description: Some required steps to set up the Business Portfolio are missing or incomplete.
Solution:
Review each setup step to make sure you’ve added all necessary details like business information, payment methods, and the WhatsApp Business account.
If unsure, go through the Business Portfolio setup again to ensure no steps are skipped.
6. Error: "Phone Number Format Incorrect"
Description: The phone number format is not accepted.
Solution:
Make sure you enter the number in international format:
+[Country Code][Phone Number].Avoid using spaces, parentheses, or hyphens.
7. Error: "API Access Denied"
Description: This error may occur due to missing permissions or restrictions in accessing the API.
Solution:
Check if the Facebook Business Manager account has the necessary permissions to access the WhatsApp Business API.
Ensure that the Facebook account you’re using has admin rights for the associated Business Manager.
If the issue persists, reauthorize the connection by reconnecting your Facebook and WhatsApp accounts.
8. Error: "Migration Failed"
Description: Errors may occur when migrating a phone number or business account from another provider or version of the API.
Solution:
Ensure you follow WhatsApp’s migration guide precisely, including backing up all necessary data and completing verification steps for the new setup.
Double-check the credentials, API keys, and verification codes to confirm they match correctly.
If the issue continues, contact your API provider or WhatsApp support for additional migration assistance.
9. Error: "Phone Number Migration Incomplete"
Description: The migration of your phone number is incomplete or stuck.
Solution:
Make sure the old account linked to the phone number is disconnected properly before initiating the migration.
Verify that you have administrative control over the phone number during the migration process.
Restart the migration process if necessary, ensuring all steps, such as the verification code, are completed correctly.
10. Error: "Messaging Limit Reached"
Description: You’ve reached your messaging limit for the day or the current messaging tier.
Solution:
WhatsApp has different messaging tiers, starting with a limited number of unique contacts per day. To increase this limit, ensure you maintain a high-quality rating for your messages and templates.
Increase your messaging tier by building trust with WhatsApp—ensure your messages are engaging, and encourage user interaction (e.g., customers replying to your messages).
Regularly check your messaging limit status and quality rating in the Business Manager dashboard under the "Account Quality" section.
11. Error: "Account Quality Rating Low"
Description: Your account has received a low quality rating, which may impact your ability to send messages.
Solution:
Review your messaging practices to ensure compliance with WhatsApp’s policies. Avoid spamming users and only send messages to contacts who have opted in.
Improve engagement by sending personalized messages and using approved templates.
Check your account status in the "Account Quality" section of the Business Manager to identify issues and improve quality.
12. Error: "Template Rejected"
Description: The message template you submitted for approval was rejected by WhatsApp.
Solution:
Ensure your template follows WhatsApp’s guidelines, such as including variable parameters (e.g., {{1}}, {{2}}) for customization and avoiding promotional language.
Avoid using sensitive or inappropriate content in templates, and make sure the template is clear, concise, and relevant.
Resubmit a revised template for approval after making necessary corrections.
13. Error: "Template Quality Rating Degraded"
Description: A template’s quality rating has dropped, which may affect its delivery.
Solution:
Monitor your template’s performance in the "Account Quality" section. If your template consistently receives negative feedback, update it to improve clarity and relevance.
Avoid repeatedly sending a template that has a low engagement rate. Test different versions or rephrase the content to be more engaging.
Ensure that templates align with the expectations set when customers opted into receiving your messages.
14. Error: "API Setup Incomplete"
Description: This message indicates that some required steps during the signup process were skipped.
Solution:
Go back and review each step to ensure all required fields are completed correctly, including business details, phone number verification, and linking your Facebook Business account.
If unsure, restart the embedded signup process from the beginning to ensure no steps are missed.
15. Error: "Internal Server Error"
Description: This generic error can happen due to server issues on WhatsApp or Facebook's end.
Solution:
Refresh the page and attempt the process again.
Check the status of WhatsApp’s API and Facebook’s systems for any ongoing outages.
If the problem remains, wait for some time before retrying as the issue may resolve itself.
Need Further Help?
If you’re still encountering errors not listed here, consider the following steps:
Visit the Meta Business Help Center for further documentation and support.
Contact WhatsApp Business API support directly through the Meta Business Manager.
By following these steps, you should be able to troubleshoot and resolve common onboarding, migration, messaging limit, and account/template quality issues with the WhatsApp Business API using embedded signup.
Last updated