WhatsApp Business API: Common Errors and Troubleshooting

This guide provides solutions for the most frequent integration, template, and messaging errors encountered when using the WhatsApp Business API with WhatsTeam.

Integration and Setup Errors

This number is registered to an existing WhatsApp account

This error occurs if your phone number is already linked to another WhatsApp Business API provider or the standard WhatsApp/WhatsApp Business mobile app.

• If using another API provider: Follow our migration guide to transfer your number to WhatsTeam.
• If using the mobile app: You must formally disconnect the number from the app before it can be used with the Cloud API. Note that this will delete your local chat history unless you have a backup.
• Still stuck? Contact our support team at support@whats.team with your WhatsApp Business Account ID and phone number for manual assistance.

Code couldn't be sent or 500 error in console

If you fail to receive a verification code or see a "500 Internal Server Error" during signup:

1. Check the console: Review your browser's developer console. Often, these are validation errors from Meta regarding your business profile settings (e.g., description too long).
2. Try the first-time flow: If you were attempting a migration, try the "First-time setup" path instead, as the account may have already been partially created.
3. Wait and retry: Meta's servers sometimes experience transient delays. Wait 5-10 minutes before requesting a new code.

WhatsApp Business Account access not shared

This occurs when the connection between your Meta Business Account and WhatsTeam hasn't been fully authorized or the permissions were revoked.

• Resolution: Re-run the embedded signup process and ensure all checkboxes for permissions are selected.

Unsupported get request or Invalid ID

Error: "Object with ID XXX does not exist..." This usually happens when a Business Manager ID is entered instead of a WhatsApp Business Account (WABA) ID. Double-check that you are using the WABA ID found in your Meta Business Settings under 'WhatsApp Accounts'.

Cannot migrate phone number

Error: "Cannot migrate phone number. The WhatsApp account that this number is registered isn't set up correctly."

1. Verify the number is fully approved in your Meta Business Suite.
2. Ensure the number is no longer active on any mobile device.
3. Take a screenshot of the verified number in your Meta dashboard and send it to our support team if the issue persists.

Cannot create certificate (2FA Conflict)

WhatsApp cannot generate a security certificate if Two-Factor Authentication (2FA) is enabled on the phone number within the mobile app. Disable 2FA in your WhatsApp app settings before attempting to connect to WhatsTeam.

Please make sure you fully authorize access

This message typically appears if there's a sync delay between Meta's approval and our platform.

• Resolution: Refresh your browser and wait 2-5 minutes for the permissions to propagate across systems.

WABA already using a payment method

This happens when a number was previously provisioned by a third-party provider that attached its own payment method. You must complete the migration process to move the number under your own Meta Business Account and payment structure.

Message Template Issues

Templates not appearing in the dashboard

If your approved Meta templates aren't showing up in WhatsTeam:

• Plain Text Only: Ensure the template doesn't use unsupported media types or complex interactive elements not yet supported in the current view.
• Language Match: Verify that the template language matches your account's language settings.
• Sync Status: Meta approval can take up to 24 hours. If it's already approved in Meta, try refreshing your connection in the dashboard.

Variable formatting (numerical placeholders)

WhatsApp Cloud API requires numerical placeholders (e.g., {{1}}, {{2}}) in the template body.

• Incorrect: Hi {{name}}, your order {{order_id}} is ready.
• Correct: Hi {{1}}, your order {{2}} is ready. You can then map these numerical variables to user attributes within WhatsTeam when sending the message.

Preventing "Marketing" reclassification

Meta may automatically reclassify "Utility" or "Service" templates as "Marketing" if they contain promotional language.

• Tip: Keep your language neutral, avoid emojis in transactional updates, and be very specific about the service purpose when submitting for approval.

Message Delivery Issues

Message is undeliverable / Receiver incapable

This usually means the recipient's WhatsApp account cannot receive the message.

• Causes: The number isn't on WhatsApp, the user hasn't accepted the latest Terms of Service, or they are using an extremely outdated version of the app.
• Solution: Ask the user (via SMS or email) to send you a message first to "warm up" the conversation and ensure their app is updated.

Messaging frequency limits

If a message fails due to "frequency limits," Meta has capped the number of marketing templates this specific user can receive in a short period to prevent spam.

• Action: Wait 24 hours before attempting to resend. Check Meta's documentation for more details.

The 24-hour conversation window

WhatsApp enforces a 24-hour service window. You can only send free-form messages if the user has replied within the last 24 hours.

• If the window is closed: You must send a pre-approved Template Message to re-engage the user. Once they reply, the 24-hour window for free-form chat reopens.

Media type not supported

If an image or document fails to send:

• Check that the file size is within Meta's limits.
• Ensure the file format (e.g., .jpg, .pdf, .mp4) is supported by the WhatsApp platform.

Recipient is part of a WhatsApp experiment

Occasionally, Meta conducts experiments where certain marketing messages cannot be delivered to specific users. If you see an error mentioning an "experiment," try sending a different message type or resending later.

Account restricted or locked

If you receive an error stating the "Account is locked," your WABA may have been suspended for policy violations.

• Resolution: Check your Meta Business Suite Support Inbox for any notifications regarding policy enforcement and follow their instructions to appeal or resolve the restriction.

Still Having Trouble?

If your issue isn't covered here, our support team is ready to help. Contact us at support@whats.team.