WhatsApp OTP Docs
WhatsApp OTP Error Codes
The current send endpoint returns clear JSON errors for validation, authentication, rate limiting, and internal failures. Your backend should map those to safe user messages and detailed server logs.
Known errors
`missing_fields` means `apiKey`, `number`, or `message` was not provided. `invalid_number` means the normalized phone number has fewer than eight digits. `invalid_api_key` means the key hash did not resolve to a user. `send_otp_failed` is an internal failure.
Plan and rate errors return HTTP 429: `daily_limit_reached` (free plan), `monthly_limit_reached` (paid plans). Reconnect WhatsApp from the console if messages queue but never arrive — a disconnected session causes delivery failure even when the API returns 202.
{
"error": "invalid_api_key"
}Handling strategy
Show neutral messages in the frontend. Log the raw error code, request purpose, user ID, and job context on the backend. Never log the raw OTP or full API key.
Use alerts for spikes in 401, 429, and 500 responses. These errors usually point to configuration, abuse, or infrastructure problems.