Developer Reference

WhatsApp API Error Codes & Troubleshooting.

Standard status codes, response payloads, common failure triggers, and recommended resolution steps for developers.

400 Bad RequestHTTP REST API
“All the fields are required (service,text,api_key,whatsaap_number)”
Cause

One or more mandatory payload parameters are missing or malformed.

Recommended Fix

Ensure 'service', 'text', 'api_key', and 'whatsaap_number' are present in the JSON body.

400 Bad RequestHTTP REST API
“Please connect WhatsApp from the dashboard before sending ... service”
Cause

The user's WhatsApp instance is in 'STOPPED', 'SCAN_QR_CODE', or inactive state.

Recommended Fix

Navigate to Console Dashboard and scan the QR code to ensure live status is 'WORKING'.

400 Bad RequestHTTP REST API
“Insufficient balance please recharge your wallet”
Cause

Prepaid wallet credit is lower than the service fee (₹0.25 for OTP, ₹0.45 for Message).

Recommended Fix

Top up your wallet via Dashboard 'Add Money' with a minimum of ₹50.

401 UnauthorizedHTTP REST API
“API key is invalid”
Cause

The passed api_key header or body parameter does not match any registered key.

Recommended Fix

Verify that the API key is active in Dashboard > API Keys.

429 Too Many RequestsHTTP REST API
“Too many requests, please try again later”
Cause

Rate limiter threshold exceeded for your IP address or key.

Recommended Fix

Implement exponential backoff or space requests with a delay (at least 2000ms for bulk).

500 Internal ErrorHTTP REST API
“Session status not found”
Cause

Underlying session runtime connection error.

Recommended Fix

Restart your session from the Wapix Dashboard.

Still experiencing integration issues?Contact Engineering Support →