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 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:

{
  "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:

{
  "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:

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.
Wait a few minutes for Meta to clear the lock; an immediate retry often still sees the old registration.
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 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:

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.
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.
Still red? Email 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

Reference

Troubleshooting: WhatsApp number registration — consumer app conflict and register failures

Troubleshooting: WhatsApp number registration — consumer app conflict and register failures

When the two codes fire

Worked envelopes

`WHATSAPP_CONSUMER_APP_CONFLICT` — the number still lives on a handset

`WHATSAPP_REGISTER_FAILED` — Meta refused the register for another reason

Troubleshooting table

See also

​Troubleshooting: WhatsApp number registration — consumer app conflict and register failures

​When the two codes fire

​Worked envelopes

​WHATSAPP_CONSUMER_APP_CONFLICT — the number still lives on a handset

​WHATSAPP_REGISTER_FAILED — Meta refused the register for another reason

​Troubleshooting table

​See also

Troubleshooting: WhatsApp number registration — consumer app conflict and register failures

When the two codes fire

Worked envelopes

`WHATSAPP_CONSUMER_APP_CONFLICT` — the number still lives on a handset

`WHATSAPP_REGISTER_FAILED` — Meta refused the register for another reason

Troubleshooting table

See also