Errors
Policy errors return an envelope with a stable code you can branch on:
error envelope
{
"error": {
"code": "outside_session_window",
"message": "Official WhatsApp outbound policy denied the request (approved_template_required)."
}
}Error codes
| Code | HTTP | Meaning |
|---|---|---|
| recipient_consent_revoked | 422 | Consent registration cannot override an opt-out. |
| recipient_suppressed | 422 | Consent registration cannot clear suppression. |
| consent_evidence_conflict | 409 | The form submission was already registered with another key; reuse its original key. |
| unauthenticated | 401 | Missing, revoked, or invalid key. |
| invalid_ability | 403 | The key lacks the required ability for this endpoint. |
| template_not_found | 404 | Template not found or not owned by your account. |
| message_not_found | 404 | Message not found or not owned by your account. |
| validation_error | 422 | Missing or invalid fields (per-field details in errors). |
| idempotency_key_required | 422 | Missing or too-short Idempotency-Key header. |
| idempotency_conflict | 409 (consent), 422 (send) | Key reused with a different request body. |
| no_whatsapp_account | 422 | No connected official WhatsApp account. |
| no_whatsapp_phone_number | 422 | No sending number available for the account. |
| outside_session_window | 422 | Text message outside the 24-hour window — use a template. |
| template_not_approved | 422 | The template is not approved by WhatsApp. |
| recipient_consent_required | 422 | The recipient has not consented, or withdrew consent. |
| send_policy_denied | 422 | Denied by an internal send policy (the message explains why). |
| rate_limited | 429 | Request limit exceeded — see Rate limits. |