API guide
Recover from a failed message
Separate acceptance from delivery
A 202 response means Buddy accepted the message. Poll GET /messages/{id} or receive message webhooks to learn the result. A failed message includes error and a human-readable reason; these asynchronous delivery codes are separate from HTTP request errors.
Choose the next action
Resolve the underlying cause before creating another message. Do not automatically retry every failure with a fresh idempotency key.
| Code | Action |
|---|---|
send_interrupted | Outcome uncertain. Reconcile before any replacement; another send may duplicate delivery. |
subscriber_opted_out | Stop marketing and utility sends. Only an explicitly requested authentication OTP is exempt. |
outside_service_window | Use an approved template or wait for a new inbound message. |
otp_expired | Ask the person to request a new code. |
template_not_found, template_paused, template_disabled, template_policy_violation | Refresh the template and its approval state. |
template_variables_mismatch, template_variables_format, media_error | Correct parameters or media before resending. |
whatsapp_billing_issue, whatsapp_account_restricted, whatsapp_reconnect_required, whatsapp_not_connected | Resolve the workspace's WhatsApp account or connection. |
recipient_unavailable, recipient_is_sender | Check the destination; do not repeatedly resend. |
rate_limited, pair_rate_limited, quality_limited, marketing_limit_reached, held_for_experiment | Reduce traffic and inspect the provider restriction; respect any retry guidance. |
whatsapp_unavailable, whatsapp_unreachable, whatsapp_error | Inspect the reason and request logs before deciding whether to send a replacement. |