> ## Documentation Index > Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt > Use this file to discover all available pages before exploring further. # Troubleshooting: WhatsApp number registration — consumer app conflict and register failures > Decode the two failures the connect flow returns after Embedded Sign-up succeeds: WHATSAPP_CONSUMER_APP_CONFLICT (422, the number still lives on the consumer WhatsApp app) and WHATSAPP_REGISTER_FAILED (502, Meta refused the Cloud API register) — with a recovery path and a back-to-green check for each. # Troubleshooting: WhatsApp number registration — consumer app conflict and register failures Embedded Sign-up can complete cleanly — token exchanged, WABA and phone selected — and the connect flow can still fail one step later, when Orbit registers your phone number for sending on the WhatsApp Cloud API. Two codes cover that step: `WHATSAPP_CONSUMER_APP_CONFLICT` (422) and `WHATSAPP_REGISTER_FAILED` (502). The [re-auth and connection recovery page](/troubleshooting/whatsapp-auth-and-connection-recovery) decodes the token-exchange and selection families that fire one step earlier; this page owns what happens when the register step itself refuses. Both codes fire on `POST /api/v1/whatsapp/connect`, after the sign-up dialog closes. The register step runs for Cloud API onboarding and is skipped in coexistence mode, where the number is already registered through the WhatsApp Business App on the handset. *** ## When the two codes fire After the dialog closes, Orbit calls the WhatsApp Cloud API `register` endpoint for your `phone_number_id` so the number can send; until that call succeeds, sends fail at Meta with "Account not registered". If Meta refuses the register, the connect flow returns one of the two envelopes below and the connection is not marked active. * `WHATSAPP_CONSUMER_APP_CONFLICT` (422) — Meta's refusal names the consumer app: the number is still registered on the WhatsApp app installed on a phone, and Meta does not allow the upgrade to Cloud API while that registration holds. * `WHATSAPP_REGISTER_FAILED` (502) — any other non-success answer from Meta on the register call: a transient upstream failure, or a Meta-side state on the number that blocks registration. The message carries the opening of Meta's response body, so the `Details:` suffix tells you which. ### Worked envelopes 422 — the number is still on the consumer app: ```json theme={null} { "error": { "code": "WHATSAPP_CONSUMER_APP_CONFLICT", "message": "This phone number is still registered as a consumer WhatsApp app. Please delete the WhatsApp app from this phone (Settings → Account → Delete my account), wait a few minutes, then reconnect here.", "status": 422 }, "meta": { "request_id": "req_01k2v8x4jt9qzm", "timestamp": "2026-10-14T09:12:44.210Z" } } ``` 502 — Meta refused the register for another reason: ```json theme={null} { "error": { "code": "WHATSAPP_REGISTER_FAILED", "message": "Could not register the phone number with WhatsApp (Meta returned 500). Details: {\"error\":{\"message\":\"Unsupported post request.\",\"type\":\"GraphMethodException\",\"code\":100}}", "status": 502 }, "meta": { "request_id": "req_01k2v9a1mr7plc", "timestamp": "2026-10-14T09:14:02.887Z" } } ``` *** ## `WHATSAPP_CONSUMER_APP_CONFLICT` — the number still lives on a handset Meta rejects the register with error code 100 and a body naming the consumer app ("Upgrading from a consumer app to WhatsApp Business Cloud API is not allowed") when the same number is registered on the WhatsApp app installed on a handset. While that registration holds, every connect run returns the same 422. You have two supported paths; pick one. **Path A — free the number, then re-run connect:** 1. On the handset that holds the number, open WhatsApp and go to **Settings → Account → Delete my account**. This deletes the consumer registration on the phone, not your Meta Business assets. 2. Wait a few minutes for Meta to clear the lock; an immediate retry often still sees the old registration. 3. Re-run the connect flow from **Settings → Channels → WhatsApp → Connect**, or re-POST `/api/v1/whatsapp/connect` with a fresh sign-up code. **Back to green:** the connect response returns `connected` with your `waba_id` and `phone_number_id`, and `GET /api/v1/whatsapp/status` reports the connection active. **Path B — keep the app live with coexistence onboarding:** if the team still answers from the phone, do not delete the app. Coexistence onboarding links the same WABA while the Business App keeps running, and its register step never touches the consumer registration. Walk the Coexistence lane in [Add a WhatsApp Business Account](/guides/whatsapp-add-waba) instead of the Cloud API lane. Do not loop the 422: re-running connect while the handset registration holds returns the same refusal every time and burns your rate budget. *** ## `WHATSAPP_REGISTER_FAILED` — Meta refused the register for another reason This is the catch-all for a non-success register answer that does not name the consumer app: a transient Meta-side failure, a number pending verification, or a stale registration Meta still sees elsewhere. The `Details:` suffix in the message is the opening of Meta's own response body, preserved verbatim — read it first, because it names the refusal. **Recovery:** 1. Check the number in **Meta Business Manager → WhatsApp Manager → Phone numbers**: it should be present on the WABA you connected and not flagged. Fix anything Meta reports, then re-run connect. 2. If the state at Meta looks clean, treat it as transient: wait a minute and re-run connect once. A second identical 502 within minutes is Meta state, not a blip. 3. Still red? Email [whatsapp-support@devotel.io](mailto:whatsapp-support@devotel.io) with the `request_id` from the envelope's `meta` block and whether Meta prompted you for the 6-digit two-factor code during sign-up — the register re-uses that code, so its state decides which retry Meta accepts. *** ## Troubleshooting table | Code | Status | Action | Expected next state | | - | - | - | - | | `WHATSAPP_CONSUMER_APP_CONFLICT` | 422 | Delete the consumer WhatsApp account on the handset (**Settings → Account → Delete my account**), wait a few minutes, re-run connect; or switch to the coexistence lane to keep the app live | Connect returns `connected`; `GET /api/v1/whatsapp/status` shows the connection active | | `WHATSAPP_REGISTER_FAILED` | 502 | Read the `Details:` suffix, fix the number's state in Meta Business Manager, re-run connect; retry once if Meta looked clean | Connect returns `connected`; a test template message delivers | *** ## See also * [WhatsApp connection recovery](/troubleshooting/whatsapp-connection) — the send-side codes that fire once a connection exists. * [WhatsApp re-authentication and Embedded Sign-up recovery](/troubleshooting/whatsapp-auth-and-connection-recovery) — the token-exchange and selection families that fire one step earlier. * [Add a WhatsApp Business Account](/guides/whatsapp-add-waba) — the Cloud API and Coexistence onboarding lanes side by side. * [Error codes](/reference/error-codes) — every `WHATSAPP_*` code the API returns, with its HTTP status. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.