Skip to main content

Troubleshooting Failed Proactive Messages

Diagnose and fix proactive messages that end up in a `FAILED` state, whether they failed at validation, at Octopods, or at the provider.

Written by Tarek Khalil

Start here

Every failed proactive message has a reason attached. Open the message in whichever surface you noticed it in:

  • Intercom Inbox App — click the failed row in View sent messages to see the details.

  • HubSpot — open the contact timeline event for the message.

  • Reach — open the message in the sent history list to see the failure reason on the message detail screen.

  • API — call GET /api/v1/whatsapp/messages/{message_id} or GET /api/v1/sms/messages/{message_id}; the response includes a failure_reason field.

The reason tells you where the failure happened. The categories below walk through the most common ones.

Recipient problems

These are the most common failures. They usually mean the number you sent to is not a valid target for the channel.

Symptom

What it means

How to fix

“Phone number is missing.”

The send request had no recipient phone number.

Supply destination_phone in the request, or confirm the contact in Intercom/HubSpot has a phone number associated.

“Invalid Phone number.”

The phone is not in E.164 format.

Re-format as + followed by the country code and the number, with no spaces or hyphens.

“Your Lead or User does not have a Phone Number associated with them.”

The selected Intercom/HubSpot contact has no phone on record.

Add a phone to the contact record, then retry.

“recipient not on WhatsApp” (WhatsApp only)

The number is correct, but is not registered on WhatsApp.

Try SMS or another channel, or confirm the recipient is on WhatsApp.

SMS reports “landline” or “unreachable”

The number is a landline, suspended, or outside a region your SMS channel supports.

Try a different number or channel. Check your SMS channel’s regional coverage.

Channel and account problems

These point at the sending side rather than the recipient.

Symptom

What it means

How to fix

“Your origin sending Channel / Number is unknown to us.”

The sending channel is not connected or is disabled.

Reconnect the channel in Settings → Channels, or pick a different channel.

“Deprecated API key.”

The API key used to send has been rotated or revoked.

Copy the current key from the channel’s settings screen and update your integration.

HTTP 429 with a “too many requests” message and a retry timestamp (WhatsApp API)

You hit the WhatsApp rate limit and Octopods blocked the API key for a short period.

Pause sends until the timestamp in the response has passed, then resume.

Template message fails with “Template does not exist or is not approved”

The template has been paused, rejected, or deleted at the provider.

Confirm the template is in the Approved state in Settings → Channels → Templates. Re-submit if needed.

Template problems

Template-only channels (WhatsApp template sends and Viber Business Messages, or VBM) add a few specific failure modes.

Symptom

What it means

How to fix

“Invalid header media URL.”

The header_attachment_url (WhatsApp) or header_image_url (VBM) was empty, not reachable, or did not match the template’s declared header type.

Host the file on a public URL and confirm it matches the header format (image, video, or document).

“The number of variables you supplied does not match the template.”

You sent too few or too many values for the template’s placeholders.

Count placeholders in the template body (and header/footer/buttons if present) and supply exactly that many values.

Variables show as {{1}} in the delivered message

At least one variable was left blank.

Fill every placeholder the template declares — blanks are rendered literally.

Provider failures

Sometimes the provider itself returns an error. These come through as the error field in an API response, or as a plain-text failure reason in the UI. The three common categories:

  • WhatsApp provider error. Causes include re-engagement window expired (no session with the user), template paused at Meta, or a WhatsApp-side rate limit. Most are temporary — retry after a short delay.

  • SMS provider error. Causes include carrier filtering, an invalid number, or a geographic region not enabled on your account. Inspect the provider’s returned error text for specifics.

  • VBM provider error. Causes include template rejection at Viber or a geographic coverage issue.

Note: If a provider error recurs consistently for the same recipient, treat it as a recipient-specific problem (wrong channel, wrong number, or recipient opt-out) rather than a provider outage.

Retry guidance

  • Transient failures (provider error, rate limit, UNKNOWN status that never resolves): retry after 30–60 seconds. If it keeps failing, escalate.

  • Validation failures (missing phone, invalid phone, missing template variables): do not retry without fixing the input first.

  • Permission failures (deprecated API key, unknown channel, template not approved): the fix is in your workspace settings, not in the request. Resolve there, then retry.

When nothing works

If a message keeps failing and none of the categories above apply:

  1. Note the exact failure reason and timestamp.

  2. Copy the message_id (API) or open the message detail view (UI).

  3. Contact Octopods support with the message ID, channel name, and failure reason.

What’s next

Did this answer your question?