plan_required — Premium channel required
What the API returns
{
"error": {
"code": "plan_required",
"message": "This action requires a Premium channel.",
"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
plan_required is an HTTP 402 error from the Wapito WhatsApp API: premium channel required. The response message reads “This action requires a Premium channel.” It is not retryable: the same request fails again until you change it. 3 endpoints can raise it, PATCH /channel/settings among them.
Why it happens
The endpoint or the option you asked for is not part of the free Sandbox plan. Sandbox exists so you can build and test against a real linked number without paying, which means it carries deliberate limits on conversations, daily messages, number checks and monthly requests. When a call crosses one of those lines the API answers here rather than half-performing the action, and details.checkout_url points at the page that lifts the limit.
How to fix plan_required
Read details.checkout_url and send the account owner there; the upgrade applies to that one channel.
If you are only testing, restructure the test to stay inside the Sandbox allowance rather than upgrading - the endpoints behave identically.
Check whether the call is genuinely premium-only or whether you simply exhausted a daily Sandbox allowance, which surfaces as quota_exceeded instead.
Endpoints that raise it
Where you will meet it
- Check 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 upgrading unlock the feature straight away?
Yes. The plan is read on every request, so the next call after the payment succeeds will be allowed. There is nothing to redeploy and no token to rotate; if you still see the error, the checkout most likely completed against a different channel.
Can one account mix Sandbox and Premium channels?
Yes. Billing is per channel, so a team can keep a Sandbox channel for staging and a Premium channel for production under the same login. Each has its own token, its own limits and its own warm-up history, and neither inherits anything from the other.
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.