English
Errors & Fixes
Errors are part of life, especially a developer's life. Every error from Zawa has the same shape:
json
{
"statusCode": 404,
"message": "session not found"
}Match the statusCode and message you got against the tables below, then follow the fix.
400: Something's Off With the Request
message | What it means | Fix |
|---|---|---|
invalid header | The id or session-id header is missing. | Send both headers on every endpoint except POST /session. |
invalid phone, group or newsletter | Send Message was called without a recipient. | Fill in one of phone, group, or newsletter. |
invalid phone or group | Send Typing was called without a recipient. | Fill in phone or group. |
invalid receiver | The number or ID has fewer than 8 digits after tidying. | Double-check the format in Core Concepts. |
type must be one of the following values: ... | Unknown type value. | Use one of the values listed in the error message. |
text should not be empty | type is text, but text is empty. | Fill in the text field. |
image should not be empty (also video, audio, and so on) | The media object for that type is missing. | Send the object, for example image for type: "image". |
image.url should not be empty, video.duration must be a positive number, etc. | A required field inside the object is empty or invalid. | Check the object tables in Send Message. |
groupId should not be empty / channelId should not be empty | A required query parameter is missing. | Add the parameter to the URL. |
404: Session Not Found
message | What it means | Fix |
|---|---|---|
session not found | The id or session-id is wrong, or the session has been deleted. | Double-check both headers. If they're right, the session is gone, so create a new session. |
A session can disappear for a few reasons: the QR code wasn't scanned within about 3 minutes, the session was disconnected for more than 30 minutes, or you deleted it yourself. See Session Lifecycle for the details.
500: Something Went Wrong While Processing
message | What it means | Fix |
|---|---|---|
session not connected | The session exists, but it isn't connected to WhatsApp right now. | Check Get Session. If qrcode is filled in, scan it again. If it's empty, wait a moment while Zawa reconnects. |
session not found | The session is in the database but not active on the server yet, for example right after a server restart. | Wait a few seconds and try again. If it keeps failing, reset the session or create a new one. |
error parser file from url ... | The media couldn't be downloaded from the URL you gave. | Make sure the URL is public, points directly at the file, and the server responds quickly. |
send timeout after 240s | Sending took longer than 4 minutes. | Use a smaller file or a faster file server. |
error compress image: ... | The status image couldn't be processed. | Make sure the URL points to a valid image (JPG or PNG). |
contacts not synced, reconnect the session or set status privacy to "only share with" | Your address book hasn't synced yet, so Zawa doesn't know who should see the status. | Reset the session and scan again, or change your status privacy on your phone to Only share with…. |
status privacy "only share with" has no contacts | Your status privacy is Only share with…, but the list is empty. | Add at least one contact to that list on your phone. |
channel not found | The channel ID is wrong, or the channel doesn't exist. | Get the right ID from Get Channels. |
internal server error or anything else | Something went wrong on the server. | Try again in a bit. If it keeps happening, let us know. |
Frequently Asked Questions
qrcode is always empty. What now?
For the first few seconds after Create Session or Reset Session, that's normal. Call Get Session every 2–3 seconds. If it's still empty after 30 seconds and isConnected is also false, try Reset Session.
I scanned the QR code, but isConnected is still false.
After scanning, WhatsApp needs a few seconds to finish linking. Wait a moment and check again. If a new QR code suddenly appears, linking failed, so scan once more.
I got a messageId, but the message never arrived.
A messageId means WhatsApp's server accepted the message. If it never arrives, it's usually because the recipient isn't on WhatsApp (Zawa doesn't check this), the number format is wrong, or WhatsApp is limiting your number for sending too many messages.
The status was posted, but some contacts can't see it.
Who sees your status depends on the status privacy setting on your phone and on your synced address book. Also remember WhatsApp's rule: statuses are only visible to people who have also saved your number in their contacts.
My number got banned by WhatsApp. Why?
Usually because it messaged lots of people who don't know you in a short time, or many recipients reported your messages as spam. Have another look at Before You Start for tips on keeping your number safe.