Skip to main content

​
Troubleshooting: WhatsApp test number held by another workspace

Setting up the WhatsApp test account starts by requesting a one-time code with POST /api/v1/whatsapp/test-account/send-otp and completes with POST /api/v1/whatsapp/test-account/verify-otp. If the phone number is already the verified test number of a different Orbit workspace, both calls refuse with a 409 carrying TEST_PHONE_REGISTERED_IN_OTHER_WORKSPACE. A phone number can bind to one workspace’s test account at a time, and the refusal is deterministic: it persists until the number is released or a different number is registered.

​
What the rejection looks like

The code arrives on the error envelope of the registration call, in the same shape as every other Orbit API refusal:
The refusal comes from the test-account route family (/api/v1/whatsapp/test-account/*), not from the WABA connect routes. A failure to connect your own WhatsApp Business Account speaks WHATSAPP_NOT_CONNECTED or CONNECTION_INVALID instead and is a different runbook: WhatsApp connection.

​
What is happening

The test account is a shared WhatsApp Business Account that Devotel operates so you can verify your integration end to end (sends, inbound replies, delivery receipts, flows) before you connect your own WABA. Inbound replies to the shared account are routed back to the workspace that holds the verified number, so a phone number can bind to exactly one workspace at a time: if a second workspace claimed the same number, the two workspaces’ test traffic would interleave. Registration therefore checks the claim before the one-time code goes out and again when the code is verified, and refuses with this 409 when the number is held elsewhere. Which workspace holds the number is deliberately not disclosed in the refusal.

​
Fixes

​
1. Register a different phone number

The fastest way through: use any phone number that can receive the verification code on WhatsApp and that no other workspace has verified. Request the code again with the new number; nothing about your workspace’s existing state needs to change.

​
2. Have the holding workspace release the number

If the number is verified in a workspace your team controls (a staging workspace, a previous project’s workspace), an owner of that workspace releases it with POST /api/v1/whatsapp/test-account/clear-verification, the same action as the test-account control in their dashboard. The release takes effect immediately, and your registration then succeeds on the next attempt. If you do not recognize any workspace that would hold the number, use the support path below.

​
3. Stale claim: open a support ticket

If the number was verified in a workspace you no longer control, or you believe the holding claim is stale (for example the number was released from your own organization and registration still refuses), open a ticket with support@devotel.io and include:
  • The request_id from meta on the refusal.
  • The phone number exactly as you sent it, in E.164 with the leading +.
  • The workspace the number was previously registered under, if known.
Support can review the claim and release stale ones.

​
What not to do

  • Do not keep retrying the same number. The refusal is a claim check, not a cooldown: repeating send-otp with the held number fails identically on every attempt, and no waiting window re-opens it.
  • Do not attempt the same number on a live WABA expecting a different verdict. The test-account pool is scoped independently of your own WABA; this gate arbitrates ownership of the shared test tier only. Connecting a WABA neither releases the number nor inherits the refusal, and the test account stays available for integration work whether or not you own a WABA.

​
See also