channel_not_connected — Channel not connected
What the API returns
{
"error": {
"code": "channel_not_connected",
"message": "The channel is not connected.",
"request_id": "req_01JRQ8F4X9N2K7YB3C5V6W8H0T"
}
}Every Wapito error is this one envelope. Branch on code, which is stable; message is written for people and can be reworded; details appears only when there is something specific to say; request_id is what to quote to support.
What it means
channel_not_connected is an HTTP 409 error from the Wapito WhatsApp API: channel not connected. The response message reads “The channel is not connected.” It is retryable: the same request can succeed later without changes. 5 endpoints can raise it, POST /messages/text among them.
Why it happens
The channel exists but its WhatsApp session is not currently linked, so nothing can be sent or read. This happens after a fresh channel is created and before pairing, when the phone unlinks the device from its linked-devices screen, when WhatsApp drops a device that has not seen its phone for around two weeks, and briefly while a session restarts. The details.status field carries the current session state.
How to fix channel_not_connected
Read details.status and the channel status endpoint before retrying - the remedy differs for a session that is starting and one that was logged out.
If the state is waiting for pairing, request a pairing code and enter it on the phone; QR remains available as a fallback.
Subscribe to the channel webhook so your system learns about a disconnect within seconds instead of discovering it on the next send.
The same failure in other stacks
If you are moving from a library or a self-hosted gateway, this is the same failure under the name that stack gives it:
WAHA session STOPPEDErrNotLoggedIn
Endpoints that raise it
Where you will meet it
- Connect a Number
Feature guide
Retry guidance
Safe to retry
The condition is transient, so the same request can succeed later without any change on your side. Retry with exponential backoff and jitter — start at one second, double each attempt, cap at a minute — and stop after a handful of tries so a stuck condition surfaces as an alert rather than a hot loop.
Frequently asked questions
How long should I wait before retrying?
If the status says the session is starting, a short backoff of a few seconds is reasonable and the call will usually succeed. If it says logged out, no amount of waiting helps - a human has to pair the number again. Branch on the status rather than retrying blindly.
Why does WhatsApp unlink a number that was working fine?
Linked devices are tied to a phone that must come online periodically. If the phone stays offline for roughly two weeks the device is dropped. Keep the phone charged and on a network, and act on the reminders Wapito sends before the deadline rather than after it.
Related
Try it on your own number
Create a channel, link a WhatsApp number by QR or pairing code, and call the API in a couple of minutes. The Sandbox plan is free and needs no card.