REFERENCE

Errors

Every failure, on every endpoint, answers with the same two-field envelope. The HTTP status tells you the class; reason tells you what happened.

json

{
  "status": false,
  "reason": "device disconnected"
}

Branch on reason, not on the status codeSeveral reasons share a status — a 400 can be a malformed body, a bad target or unparseable batch JSON. The vocabulary is closed and each value is stable; new ones may be added, but an existing one never changes meaning. Never match on a substring.

The vocabulary

Field	Type	Description
token invalid	reason	The token is missing, malformed or revoked. Not retryable — fix the credential.
input invalid	reason	The body failed validation. Check the field table on the endpoint page; the combination matters as much as each field.
target invalid	reason	No recipient survived normalization. Check the number and `countryCode`.
url invalid	reason	The media URL is malformed, or it resolves to an address the gateway refuses to fetch from — loopback, link-local or a private range.
url unreachable	reason	The media URL could not be fetched in time. Retryable once the host is up.
file format not supported	reason	That media type cannot be sent. Convert it first.
file size must under 4MB	reason	The media exceeds the 4 MB ceiling. Compress it or host it smaller.
insufficient quota	reason	The device spent its monthly quota. Nothing was sent — quota is all-or-nothing per request. Raise it in the dashboard or wait for the period to roll over.
device disconnected	reason	The device is not connected and `connectOnly` was set. Reconnect it, or send with `connectOnly: false` to queue until it comes back.
JSON format invalid	reason	A `data` batch was not valid JSON, or was not an array.
rate limited	reason	Too many requests for this token. Wait the seconds in `retryAfter` — the `retry-after` header carries the same number.
unauthenticated	reason	No credential at all was presented.
forbidden	reason	The token is valid but the wrong kind for this endpoint — an account token cannot send. Use the device token from the device page.
not found	reason	No such resource for this token. A resource that belongs to somebody else answers the same way — the API never confirms an id exists outside your own device.
internal error	reason	Something failed on our side. Safe to retry.
device already connect	reason	The device is already connected; the control was a no-op.
device already disconnected	reason	The device is already disconnected; the control was a no-op.
device not found	reason	The token has no device, or it was deleted.
engine unavailable	reason	The component that holds the WhatsApp sockets is not reachable. Retry shortly.
qr not ready	reason	A pairing code has been requested but is not issued yet. Poll again.
message not found	reason	No message with that id belongs to this device.
message not cancellable	reason	The message has already left. Only one still waiting, queued or pending can be cancelled, and only one still waiting can be rescheduled.

Rate limits

A rate limited response carries retryAfter in seconds, and the same value in the standard retry-after header. Respect it rather than retrying immediately — the limit is per token, so a tight retry loop only starves your own other calls.