> ## 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 connection, re-authentication, tier limits, and quality pauses > Get a disconnected WhatsApp Business Account sending again — re-run Embedded Sign-up for a stale token, distinguish NOT_CONNECTED from CONNECTION_INVALID, work through tier limits and quality pauses, and bundle the right payload for support. # 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](/troubleshooting/whatsapp-template), and the send-window errors (`WHATSAPP_OUTSIDE_24H_WINDOW` and friends) live in [WhatsApp 24h freeform window](/guides/whatsapp/24h-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. | Symptom | Most likely cause | What to do | | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Dashboard shows the WABA as disconnected, or a send returns `WHATSAPP_NOT_CONNECTED`** | The organization has no connected WABA at all — Embedded Sign-up never completed, or the connection was deleted | Run (or re-run) Embedded Sign-up from **Settings → Channels → WhatsApp → Connect**. The full flow is in [WABA setup](/guides/whatsapp/waba-setup#step-3-embedded-sign-up-flow) | | **Connection existed, now sends return `WHATSAPP_CONNECTION_INVALID`** | The stored Meta access token no longer resolves — the token expired or was revoked at Meta (`WHATSAPP_TOKEN_EXPIRED` surfaces on the same failure class), or the WABA row was edited outside the normal flow | Re-authenticate (next section). A retry without re-authentication fails identically — the token is dead, not busy | | **`WHATSAPP_BYO_INCOMPLETE`** | You connected a bring-your-own (BYO) WABA but the connection row is missing its access token or phone number id — the BYO form was half-completed | Finish the BYO setup fields, or disconnect and re-connect through Embedded Sign-up. The error is fail-fast: retrying the same send always returns the same code | | **A second WABA or phone number won't stick after the sign-up popup closes** | The popup closed before Meta returned control to Orbit — common on Safari and corporate SSO setups | Re-trigger from **Settings → Channels → WhatsApp → Connect**; Meta preserves the partial state, so the re-run resumes instead of duplicating the WABA. Never create a second WABA for the same business — it splits your quality rating and template inventory across two accounts | | **Sends throttle with `WHATSAPP_TIER_LIMIT_EXCEEDED` (HTTP 429)** | The WABA is at its current messaging-tier ceiling (250 → 1,000 → 10,000 → 100,000 unique recipients per 24h) | Tier handling section below — this is backpressure, not a fault | | **WhatsApp Business Calling returns `WHATSAPP_SHARED_CALLING_QUALITY_PAUSED` (HTTP 503)** | Meta rated the platform's shared calling phone `quality_rating=RED` and paused calling on it | Quality pauses section below — your own WABA numbers are unaffected | ## `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](/guides/whatsapp/waba-setup#step-3-embedded-sign-up-flow). If the WABA lives at another provider and you are reconnecting to move it, follow [WABA migration](/guides/whatsapp/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](/guides/whatsapp/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](/guides/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](/guides/whatsapp/business-calling#step-2-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. ## 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 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](mailto: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 * [Troubleshoot a WhatsApp template](/troubleshooting/whatsapp-template) — pending, rejected, paused, and reclassified templates on an already- healthy connection. * [Troubleshoot WhatsApp Flow submissions](/troubleshooting/whatsapp-flow-submissions) — missing submissions, empty lists, and publish-state failures on the Flow layer. * [WABA setup](/guides/whatsapp/waba-setup) — first-time connection, approval timelines, and the messaging-tier table. * [WABA migration](/guides/whatsapp/waba-migration) — move an existing WABA from another provider onto Orbit. * [WhatsApp Business Calling](/guides/whatsapp/business-calling) — enable calling on your own number and the permission flow that keeps quality green. * [Error codes](/reference/error-codes) — every `WHATSAPP_*` code the API returns, with its HTTP status.