channel_locked — Channel is locked
What the API returns
{
"error": {
"code": "channel_locked",
"message": "This channel is locked.",
"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_locked is an HTTP 403 error from the Wapito WhatsApp API: channel is locked. The response message reads “This channel is locked.” It is not retryable: the same request fails again until you change it. 4 endpoints can raise it, POST /messages/text among them.
Why it happens
The channel has been placed on hold and every write is refused until the hold is lifted. A lock happens when a subscription payment fails, when abuse controls trip, or when an operator freezes a channel on request. Reads that do not change anything may still work, so your dashboard keeps rendering while sends stop. The details.reason field says which of those applies so support can act without guessing.
How to fix channel_locked
Read details.reason and treat a billing lock differently from an abuse lock - only one of them is fixed with a card.
For a billing lock, update the payment method from the customer portal; the channel unlocks when the invoice clears.
For an abuse lock, stop the sending job first, then contact support with your request_id - restarting the job will not help.
Endpoints that raise it
Where you will meet it
- Connect a Number
Feature guide
Retry guidance
Do not retry as sent
The same request fails the same way until something changes: the body, the credential, the recipient or the state of the channel. Keep it off every retry loop, fix the cause above, and send a corrected request once.
Frequently asked questions
Does a locked channel lose its WhatsApp session?
Not immediately. The underlying session usually stays linked so that nothing has to be re-paired once the lock is lifted, but a lock that lasts long enough will run into WhatsApp's own inactivity unlink at roughly two weeks. Resolve the lock quickly to avoid re-pairing the phone.
Do webhooks keep arriving while a channel is locked?
Inbound events may still be delivered so you do not lose the record of what happened, but outbound calls are refused. Treat a stream of inbound events with failing sends as a strong signal to check the channel status endpoint rather than to keep retrying.
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.