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 can return HTTP 429. Treat them as recoverable for the user but important for monitoring because repeated 429 responses may indicate abuse, a broken retry loop, or a plan mismatch.
{
"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.