Error shape
HTTP/1.1 404 Not Found
Content-Type: application/json
{ "error": "unknown or unpaired clientId" }Successful sends can additionally carry a warning alongside status: "sent" — treat those as success and log the warning.
Status codes
| Status | Meaning | Retry? |
|---|---|---|
400 | Malformed request or missing fields. | No — fix the request. |
401 | Bad or missing token. | No — fix credentials. |
404 | Unknown or unpaired clientId; message or media not found. | No — check /check-state or /qr. |
409 | State conflict (already paired; session not connected for a lookup). | After the state changes. |
500 | Storage failure on our side. | Once, then contact support. |
502 | WhatsApp rejected the operation, the upstream fetch failed, or the session's node is unavailable. Nothing was delivered. | Yes — exponential backoff. |
503 | Readiness: database unreachable (health) or storage not configured (media). | Yes — with backoff. |
Common messages
| Message | What it means |
|---|---|
clientId must contain letters and digits only (no symbols) | Rename the clientId — hyphens, dots and spaces are not allowed. |
unknown clientId — call /start first | The session was never started on this account. |
unknown or unpaired clientId | Started but not yet scanned, or unlinked. Poll /qr. |
client is not connected | Reconnect in progress or a terminal state. Check /health/clients. |
failed to send message: … | WhatsApp's reason follows. Common: recipient not on WhatsApp, blocked, group not found. |
sent but failed to save to inbox: … | Not an error status — a warning on a 200. Delivered; hosted history write failed. |
no stored message for this chat to anchor the unread mark | /mark-unread needs hosted history for that chat. |
the user has hidden their profile picture from you | Privacy setting on their side; url is empty, status 200. |