Skip to main content

​
Troubleshooting: WhatsApp connection, re-authentication, tier limits, and quality pauses

A WhatsApp connection problem shows up one of four ways: the dashboard says the WABA is disconnected, sends fail against a WABA that used to work, a new connection run will not stick, or Meta pauses the shared calling phone for quality. This page covers the connection layer only — once the WABA is connected and healthy, template-level failures live on Troubleshoot a WhatsApp template, and the send-window errors (WHATSAPP_OUTSIDE_24H_WINDOW and friends) live in WhatsApp 24h freeform window.
Connection state, tier assignments, and quality ratings are Meta’s call, not Orbit’s — Orbit stores what Meta’s Embedded Sign-up hands back and enforces the limits Meta applies. When this page says “reconnect,” the authoritative state change always happens in Meta’s OAuth dialog, not in the Orbit dashboard.

​
Symptom map

Work the table top-down — the error codes in the first column are the exact strings the API returns, so grep your logs for them.

​
WHATSAPP_NOT_CONNECTED vs WHATSAPP_CONNECTION_INVALID

These two codes look similar and demand opposite fixes:
  • WHATSAPP_NOT_CONNECTED — there is no WABA row for your organization at all. Nothing to repair; you have to run the connection flow for the first time. The typical trigger is a send from a fresh account, or a send after someone removed the channel.
  • WHATSAPP_CONNECTION_INVALID — a WABA row exists, but the credentials it carries cannot be used. The stored access token fails to decrypt or resolve, which happens after the token is revoked in Meta Business Manager, after Meta’s 60-day token expiry on tokens that were never refreshed, or after the row was edited by hand. The fix is re-authentication, not first-time setup.
The distinction matters because re-running Embedded Sign-up for a NOT_CONNECTED account creates a connection, while the same run on a CONNECTION_INVALID account refreshes the token in place and preserves your templates, phone numbers, and quality history. Reconnecting is never destructive — but deleting the channel and starting over is, so prefer the re-authentication path whenever a row exists.

​
Re-authentication flow

A stale token looks like this: the WABA still appears in the dashboard, template reads and phone-number reads start failing, and sends return WHATSAPP_CONNECTION_INVALID or Meta’s WHATSAPP_TOKEN_EXPIRED. To replace the token:
  1. Go to Settings → Channels → WhatsApp and click Connect.
  2. Complete the Meta OAuth dialog with the same Facebook account and the same Business Manager as the original connection. Meta returns a fresh token for the existing WABA; Orbit overwrites the credential in place.
  3. Send a template message to a known-good internal recipient to confirm the path — the same pre-flight checks that failed before now pass.
Step-by-step screenshots and the popup edge cases (Safari, corporate SSO) are in WABA setup — Embedded sign-up flow. If the WABA lives at another provider and you are reconnecting to move it, follow WABA migration instead — the migration flow is the same OAuth dialog with the number-porting steps wrapped around it.

​
Tier limits — WHATSAPP_TIER_LIMIT_EXCEEDED

Meta caps every WABA at a number of unique recipients per rolling 24 hours: 250 on a new account, then 1,000, 10,000, and 100,000 as the account proves itself. When your sends exceed the current tier, Orbit returns WHATSAPP_TIER_LIMIT_EXCEEDED (HTTP 429) instead of queueing messages Meta would reject anyway.
  • 429 means backpressure, not failure. Retry with backoff inside the same 24-hour window; the recipients already delivered count toward the tier, and the queue clears as the window rolls.
  • Tiers advance automatically. Meta promotes a WABA when it sustains volume near the current ceiling with a Medium or Green quality rating over a 7-day window. The tier table and the promotion rules are in WABA setup — Messaging limits.
  • Quality is the throttle. A Low rating freezes progression and a sustained Low rating drops the WABA a tier — which cuts the cap without any code change on your side. If the tier fell, fix opt-in and the first line of your templates before asking for the tier back.
  • Plan growth around the ceiling. For a campaign that exceeds the current tier, split the send across 24-hour windows rather than fighting the 429 — recipients who fail with the tier error are not penalized, but hammering the API burns your rate budget.

​
Quality pauses — two distinct classes

“Quality pause” covers two unrelated failure classes; treat them separately. Calling-quality pause (WHATSAPP_SHARED_CALLING_QUALITY_PAUSED, HTTP 503). WhatsApp Business Calling on Orbit can run over the platform’s shared calling phone. When recipients report or block calls from that shared number often enough, Meta rates it RED and pauses calling until the rating recovers. During a pause, calling APIs return this error while messaging keeps working. Your options, in order of preference:
  1. Wait it out if your volume is low. Meta recalculates the rating continuously; a RED state driven by a single bad campaign usually recovers in days once the traffic stops.
  2. Move calling onto your own WABA number. Enable calling on a phone number attached to your own WABA — per WhatsApp Business Calling — and your calling traffic stops sharing one phone’s reputation with every other tenant. This is the durable fix when calling is core to the workload.
  3. Fix the traffic that burned the rating. Unsolicited outbound calling without an explicit permission grant is what Meta weighs — send the call_permission_request template first and only call recipients who granted it. The permission flow is in Calling permissions.
The goal is unblocking your numbers without escalating the quality decision with Meta — for the shared phone, the operator side handles any appeal; your lever is which number your calls use. Per-call action failures (WHATSAPP_CALL_ACTION_FAILED). Meta rejected a single call-control action — accept, reject, or terminate — on one call. That is not a pause and not a quality event: the call id no longer matches an active call (the recipient hung up first, or the call timed out), or the action arrived in the wrong order. Handle it idempotently — treat the failed action as already-final and move on. Only if every action on every call fails should you suspect the connection layer instead, and the codes above (CONNECTION_INVALID, TOKEN_EXPIRED) will appear together with it.

​
Account lock — WHATSAPP_ACCOUNT_LOCKED (Meta 131031)

A lock is Meta’s account-level enforcement: Meta locked the WhatsApp Business Account outright after a sustained policy issue, and every send against it returns WHATSAPP_ACCOUNT_LOCKED. Distinguish it from the two nearby states:
  • Not a quality drift (WHATSAPP_ACCOUNT_QUALITY_LOW, Meta 133000). A low-quality WABA still sends — Meta only throttles tiers while it recovers. A locked WABA is a hard stop on every send until the lock lifts.
  • Not a connection fault (WHATSAPP_CONNECTION_INVALID). The credentials are fine; re-authentication does nothing because Meta is refusing the account, not the token.
Recovery happens at Meta, not in Orbit — no in-platform toggle lifts a lock:
  1. Find the violation before you appeal. Review your recent template content against the WhatsApp content policy and check the quality surfaces — GET /api/v1/brand-identity/status plus Meta Business Manager’s Account Quality page — so the appeal names what changed. An appeal with no visible fix usually returns the same verdict.
  2. Appeal through Meta Business Support. Open the appeal from Meta Business Manager (Business Support Home → the restricted account), or through email support if your org has it routed. Meta reviews the account against its commerce and business-messaging policies; the lock lifts only on that decision.
  3. Fix the traffic while the appeal runs. Pause the campaign class that drove the policy strike (unsolicited marketing, mismatched template categories, missing opt-in) — a second strike while the first is under review weighs the decision against you.
The lock follows the account, so the checklist below matters here.

​
What not to do

  • Do not create a second WABA to escape a tier or a quality freeze. Tier budgets are per WABA and Meta ties the two accounts to the same business; the evasion resets your quality history and usually ends with the duplicate account restricted.
  • Do not disconnect and re-connect the WABA expecting a lock reset. WHATSAPP_ACCOUNT_LOCKED follows the account at Meta, not the Orbit connection row — the re-run of Embedded Sign-up rebinds a locked WABA and sends fail the same way. Only the Meta appeal lifts a lock.
  • Do not delete the channel when a token goes stale. Deleting removes the phone-number mapping, templates stay at Meta but lose their Orbit linkage, and the reconnect has to rebuild them. Re-run Embedded Sign-up against the existing WABA instead.
  • Do not poll the reconnect in a loop. A send every few seconds against a dead token returns the same error each time and eats your API rate budget; re-authenticate once in the dashboard, then verify once.

​
Escalation payload

If you have worked the page and the connection is still down, email whatsapp-support@devotel.io with these three items so we can trace the WABA with Meta without a back-and-forth:
  1. Your WABA id (Meta Business Manager → WhatsApp Manager, or the waba_id on any template or phone-number record).
  2. The phone number that fails, in E.164 (+15551234567).
  3. The most recent error code verbatim — e.g. WHATSAPP_CONNECTION_INVALID, WHATSAPP_TOKEN_EXPIRED, or WHATSAPP_TIER_LIMIT_EXCEEDED — plus the timestamp of one failing request.

​
See also