| Status | Message | What to do |
|---|---|---|
| 401 | Missing x-api-key header | Add the header |
| 401 | Invalid API key | The key was regenerated or mistyped. Copy it again from the Notification page |
| 403 | Workspace is suspended | Contact support |
| 403 | Recipient has opted out | The contact replied STOP. WhatsApp policy forbids messaging them until they restart the conversation |
| 400 | Request body must be valid JSON | Fix the body, and send Content-Type: application/json |
| 400 | Missing required field(s) | A required field is absent after mapping. Check the mapper paths against a real payload |
| 400 | recipient_phone is not a valid number | Send full international format with the country code |
| 400 | Template needs value(s) not in the payload | A template variable has nothing to fill it. Map that field, or edit the template |
| 409 | No template configured | Choose an approved UTILITY template on the Notification page |
| 409 | Template is not approved yet | Wait for Meta, then use Sync Status |
| 409 | Configured template no longer exists | It was deleted. Select another |
| 422 | Invalid or missing type | Use appointment, delivery or status-update |
| 422 | Unknown business | The business parameter is not a group in this workspace |
| 500 | Could not read the notification configuration | The database schema is behind. Run the setup-db migration |
| 503 | Could not verify the recipient opt-out status | Transient. Retry |
| 202 | Notification received and queued | Accepted. Check Delivery for the send result |
A 202 means MsgOrb queued the message, not that WhatsApp delivered it. Meta reports delivery failures asynchronously, so the Delivery page is where you confirm the outcome.