Phone Migration & WABA

Phone migration errors occur when attempting to migrate a business phone number from one WhatsApp Business Account to another, or between solution providers. WABA errors cover issues related to WhatsApp Business Account management and synchronisation.

Migration is a sensitive operation - errors here can result in messaging downtime. Always follow the official migration documentation and ensure all prerequisites are met before initiating a migration.

Error 2388012 - Phone Exists

Phone Number Already Exists in Your Account

ERROR CODE

2388012

ERROR SUMMARY

Phone Number Already Exists in Your Account

ERROR DESCRIPTION

The phone number you are attempting to migrate already exists in the destination WhatsApp Business Account. You cannot migrate a number to an account that already contains it.

Migration/management error.

RESOLUTION & TROUBLESHOOTING STEPS

1. Verify the destination WABA's phone number list before initiating migration.

2. If the number is already in the destination WABA, no migration is needed - it is already in the right place.

3. If you intended to migrate to a different WABA, verify the target WABA ID in your request.

OTHER NOTES

This error serves as a safeguard to prevent duplicate number entries. Check both the source and destination WABAs before migration.

Error 2388091 / 2388093 Eligibility

Phone Number Not Eligible for Registration Code (Migration Use Case)

ERROR CODE

2388091 / 2388093

ERROR SUMMARY

Phone Number Not Eligible for Registration Code (Migration Use Case)

ERROR DESCRIPTION

The phone ownership verification APIs (request code / verify code) are being called for a number that is not actually in the process of migration. These endpoints are only available for the phone migration use case.

Migration error.

RESOLUTION & TROUBLESHOOTING STEPS

1. If your goal is to register and verify the number (not migrate it), use the standard registration flow: POST /{phone-number-id}/register and POST /{phone-number-id}/verify_code.

2. Review the registration documentation at https://developers.facebook.com/documentation/business-messaging/whatsapp/solution-providers/registering-phone-numbers.

OTHER NOTES

Phone migration APIs are a separate set of endpoints from standard registration APIs. Ensure you are calling the correct endpoints for your use case.

Error 2388103 - No Migration

Cannot Migrate Phone Number — Multiple Possible Causes

ERROR CODE

2388103

ERROR SUMMARY

Cannot Migrate Phone Number — Multiple Possible Causes

ERROR DESCRIPTION

This error code covers multiple distinct migration failure scenarios, each with a different 'details' message: (1) Webhooks not set up on destination WABA, (2) Number eligible for direct add (not migration), (3) Display name not approved, (4) Source WABA using deprecated OBO model, (5) No payment account on WABA, (6) Generic migration error, (7) Numbers belong to different Business Manager accounts, (8) Destination WABA not approved, (9) 'Messaging For' request not approved.

Migration error.

RESOLUTION & TROUBLESHOOTING STEPS

1. Webhooks not set up: Subscribe your app to webhooks on the destination WABA before initiating migration.

2. Number eligible for direct add: Register the number directly instead of using migration APIs.

3. Display name not approved: Get the phone number's display name approved in WhatsApp Manager before migration.

4. OBO model issue: The source WABA uses the deprecated On-Behalf-Of model. Contact Meta Support.

5. No payment account: Set up a credit line and share it with the WABA.

6. Generic error: Try again after some time; contact support if it persists.

7. Different Business Manager: Migrate to a WABA representing the same business.

8. WABA not approved: Complete business verification for the destination WABA.

9. 'Messaging For' not approved: Ask your client to approve the Messaging For request in Meta Business Suite.

OTHER NOTES

Always check the 'details' field carefully — the specific message tells you exactly which sub-scenario you are dealing with.

The On-Behalf-Of (OBO) model is deprecated. If you encounter OBO-related migration issues, contact Meta Support for migration assistance to the WABA Sharing model.

Error 2494100 Maintenance

Account Is in Maintenance Mode

ERROR CODE

2494100

ERROR SUMMARY

Account Is in Maintenance Mode

ERROR DESCRIPTION

The business phone number is currently in maintenance mode, which prevents migration and registration operations.

Migration/registration error.

RESOLUTION & TROUBLESHOOTING STEPS

1. Wait a few minutes and retry.

2. Maintenance mode is typically short-lived.

3. If it persists, contact Meta Support.

OTHER NOTES

Maintenance mode can be triggered by account upgrades, throughput changes, or other backend operations. It is generally temporary.

Error 2593079 Marked Migration

WABA Already Marked for Migration to Different Solution ID

ERROR CODE

2593079

ERROR SUMMARY

WABA Already Marked for Migration to Different Solution ID

ERROR DESCRIPTION

The WhatsApp Business Account has already been flagged for migration to a different solution ID. This relates to the deprecated On-Behalf-Of (OBO) ownership model.

WABA management error.

RESOLUTION & TROUBLESHOOTING STEPS

1. The OBO account ownership model is now deprecated. Do not attempt further OBO transfers.

2. Contact Meta Support for guidance on migrating to the WABA Sharing model.

3. Refer to the OBO Model Deprecation documentation at https://developers.facebook.com/documentation/business-messaging/whatsapp/solution-providers/obo-model-deprecation.

OTHER NOTES

If you are still using the OBO model, plan your migration to the WABA Sharing model as soon as possible.

Error 2593085 Invalid WABA

Invalid WABA for OBO Mobility - Not Eligible for OBO Ownership Transfer

ERROR CODE

2593085

ERROR SUMMARY

Invalid WABA for OBO Mobility — Not Eligible for OBO Ownership Transfer

ERROR DESCRIPTION

The WABA is not eligible for an On-Behalf-Of ownership transfer. This may be because the WABA is already owned by the business customer (using the WABA Sharing model) or the business customer has not yet accepted the OBO request.

WABA management error.

RESOLUTION & TROUBLESHOOTING STEPS

1. Check whether the WABA already uses the WABA Sharing model — if so, OBO transfer is not applicable.

2. If the OBO request is pending, ask the business customer to accept it in Meta Business Suite.

3. Remember that the OBO model is deprecated — focus on transitioning to WABA Sharing.

OTHER NOTES

Both 2593079 and 2593085 are OBO-specific errors. New integrations should exclusively use the WABA Sharing model.

Error 2593107 Sync Limit

Synchronisation Request Limit Exceeded

ERROR CODE

2593107

ERROR SUMMARY

Synchronisation Request Limit Exceeded

ERROR DESCRIPTION

The maximum number of allowed synchronisation API calls for this phone number has been exceeded. The synchronisation endpoint can only be called once to sync contacts and once to sync messaging history.

HTTP Status: 400 Bad Request.

RESOLUTION & TROUBLESHOOTING STEPS

1. Do not retry the synchronisation request — you have already used the allowed calls.

2. If you need to re-synchronise, you must offboard the business customer and onboard them again.

3. Review the Onboarding Business App Users documentation at https://developers.facebook.com/documentation/business-messaging/whatsapp/embedded-signup/onboarding-business-app-users#synchronizing-whatsapp-business-app-data.

OTHER NOTES

Synchronisation is a one-time operation per onboarding. Design your onboarding flow to use the single synchronisation opportunity correctly.

Error 2593108 - Time Window

Synchronisation Request Made Outside Allowed Time Window

ERROR CODE

2593108

ERROR SUMMARY

Synchronisation Request Made Outside Allowed Time Window

ERROR DESCRIPTION

The synchronisation request was made more than 24 hours after the business customer was onboarded. Synchronisation of contacts and messaging history must be initiated within 24 hours of onboarding.

HTTP Status: 400 Bad Request.

RESOLUTION & TROUBLESHOOTING STEPS

1. The time window has passed and cannot be extended.

2. Offboard the user and re-onboard them to reset the 24-hour window.

3. Update your onboarding flow to trigger synchronisation immediately upon successful onboarding, well within the 24-hour window.

OTHER NOTES

Build the synchronisation API call as an immediate post-onboarding step in your integration pipeline, not a deferred or optional step.