channel_not_in_qr_state — Not waiting for a QR
What the API returns
{
"error": {
"code": "channel_not_in_qr_state",
"message": "The channel is not waiting for a QR scan.",
"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_in_qr_state is an HTTP 409 error from the Wapito WhatsApp API: not waiting for a QR. The response message reads “The channel is not waiting for a QR scan.” It is retryable: the same request can succeed later without changes. 2 endpoints can raise it, GET /channel/qr among them.
Why it happens
You asked for a QR image or a pairing code while the channel was in some other state. A QR is only meaningful during the short window when the session is waiting to be linked. If the channel is already connected there is nothing to scan, and if it is still starting up the engine has not produced a code yet. Polling this endpoint on a loop is the usual way to meet this error.
How to fix channel_not_in_qr_state
Poll the channel status endpoint and only ask for a QR or pairing code once the state says the session is waiting to be linked.
If the channel is already connected and you want to relink a different phone, log the channel out first and then pair again.
Prefer the pairing code over the QR: new QR links have been unreliable across engines since mid-2026, and a code typed on the phone is more robust.
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 often should I poll while waiting for a code?
Once every two or three seconds is plenty, with a hard stop after a minute or two. Codes expire quickly and a tight polling loop only produces this error faster. Better still, listen to the channel webhook, which pushes each state change as it happens.
Can I get a pairing code for a number already linked elsewhere?
Not while this channel holds the session. WhatsApp allows several linked devices for one phone, but a Wapito channel owns one of those slots. Log out of this channel to release the slot, or create a separate channel if you genuinely need two.
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.