VALIDATION_ERROR | 400 | Missing or invalid field. message names it. | Fix the request. |
INVALID_JID | 400 | The number is not on WhatsApp, or the JID is malformed. | Check the number; do not retry. |
ALREADY_LOGGED_IN | 400 | Login requested for a device that is already logged in. | Nothing, or log out first. |
DEVICE_ID_REQUIRED | 400 | No device given and the server has zero or several devices. | Send X-Device-Id. |
AUTHENTICATION_ERROR | 401 | The device is not logged in to WhatsApp (or WhatsApp authentication failed). | Check /devices/{id}/status; pair again if needed. |
NOT_FOUND | 404 | Resource not found (message, chat, schedule…). | Check the ID. |
DEVICE_NOT_FOUND | 404 | X-Device-Id names an unknown device. | Check the slot ID or JID. |
AVATAR_HIDDEN | 403 | Profile picture is hidden by privacy settings. | Do not treat this as confirmed absence or erase a cached picture solely on this result. |
AVATAR_NOT_SET | 404 | Contact has no profile picture. | Clear a cached picture only after checking this code, not any 404. |
CROSS_SITE_REQUEST_BLOCKED | 403 | Browser origin is not trusted. | Serve the dashboard over HTTP(S) and configure the exact trusted origin. |
CONTEXT_ERROR | 408 | The operation was cancelled or timed out internally. | Retry once. |
WA_REACHOUT_TIMELOCK | 429 | WhatsApp temporarily blocks new chats from this account. | Stop outreach; see Sending limits. |
INTERNAL_SERVER_ERROR | 500 | Unexpected failure, including recovered panics. | Retry with backoff; check logs. |
QR_CHANNEL_ERROR | 500 | Could not obtain a QR code. | Retry login. |
SESSION_SAVED_ERROR | 500 | Could not persist the session. | Check storage and permissions. |
UPLOAD_MEDIA_ERROR | 500 | Media upload to WhatsApp failed. | Retry; check size and format. |
WEBHOOK_ERROR | 500 | Webhook configuration or delivery error. | Check the webhook URL. |
INVALID_WA_CLI | 500 | The device’s WhatsApp client is not initialized. | Reconnect or log in again. |
DEVICE_MANAGER_UNAVAILABLE | 503 | The device manager is not initialized. | Retry shortly; check startup logs. |
GATEWAY_TIMEOUT | 504 | The request exceeded 45 seconds. | The action may still complete; check before retrying. |