payload_too_large — Payload is too large
What the API returns
{
"error": {
"code": "payload_too_large",
"message": "The request payload is too large.",
"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
payload_too_large is an HTTP 413 error from the Wapito WhatsApp API: payload is too large. The response message reads “The request payload is too large.” It is not retryable: the same request fails again until you change it. 4 endpoints can raise it, POST /media among them.
Why it happens
The body you sent exceeds the size this plan allows. It usually means a media upload above the plan ceiling, but it also catches an oversized JSON body such as a bulk number check with far too many entries, or a base64 blob pasted inline instead of uploaded. WhatsApp has its own per-type media ceilings underneath, so a file can be refused here even when your plan would technically allow it.
How to fix payload_too_large
Upload media through the media endpoint and send the returned id rather than inlining bytes in the JSON body.
Compress or transcode before sending: a video re-encoded for mobile is usually a fraction of the original and arrives faster.
Split bulk requests into smaller batches and page through them instead of sending one enormous array.
Endpoints that raise it
Where you will meet it
- Post Status
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
Is the limit set by Wapito or by WhatsApp?
Both, and the smaller one wins. Your plan sets an upload ceiling and WhatsApp enforces its own maximum for each media type. A file that passes the plan check can still be refused by the engine, so treat the published plan number as an upper bound rather than a guarantee.
Does a rejected upload count against my quota?
The upload is refused before it reaches the engine, so no message is sent and no send quota is consumed. It still costs you a request against the monthly request allowance, which is another reason to check file sizes client-side before uploading.
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.