Delivery Error Codes

When a message fails, the message.failed webhook payload carries two fields describing why:

error_code - a short, stable code identifying the failure (e.g. "300", "012").
error_message - the human-readable label for that code, exactly as listed in the table below.

The same codes appear in the project error report (GET /v1/projects/{id}/error-codes), conversation CSV exports, and data exports, so a code seen in a webhook can be cross-referenced anywhere else in the platform.

Code format

Most codes are three digits with leading zeros preserved ("001", "012", "300"), so they align at a consistent width. A small number of codes fall outside that family and arrive at their full length (e.g. "41000"). Treat error_code as an opaque string, not a number: parsing "012" as an integer loses the leading zero. If a message fails with a code not listed below, the code is passed through as-is with a best-effort error_message (or "Unknown error" when no further detail is available). Email support@politicalcomms.com with the code and the message_id and we will investigate.

Category	How to react
`opted_out`	Permanent for that recipient. They sent STOP (or similar); do not message them again. The platform suppresses them automatically.
`landline_or_unreachable`	Permanent. The number cannot receive text messages; remove it from your lists.
`invalid_destination`	Permanent. The number is invalid, deactivated, or unreachable; remove it from your lists.
`blocked_as_spam`	Content or consent problem. Review your message content and recipient consent before resending.
`carrier_rejected`	The recipient’s network declined or did not accept the message. Often transient; safe to retry later.
`rate_limited`	Transient. Sending volume exceeded a limit; throughput recovers on its own.
`expired`	Transient. The message timed out before delivery, usually a throughput symptom.
`unregistered_campaign`	Sender-side registration issue. Contact support if it persists.
`invalid_sender`	Sender-side number issue. Contact support if it persists.
`invalid_content`	The message body or media was rejected. Adjust the content and resend.
`configuration`	Sender-side setup issue. Contact support if it persists.
`loop`	A message forwarding loop was detected.
`unknown`	Unclassified. Contact support with the `message_id`.

All error codes

The error_message column is the exact string delivered in the webhook payload.

Code	Error message	Category	Description
`001`	Not routable	`landline_or_unreachable`	The destination is a landline or a number that cannot receive text messages.
`002`	Blocked as spam (temporary)	`blocked_as_spam`	The message was flagged as spam and temporarily blocked. Review recipient consent before resending.
`003`	Blocked as spam (permanent)	`blocked_as_spam`	The message was flagged as spam and the sending number is permanently blocked.
`004`	Rejected by destination	`carrier_rejected`	The recipient’s network declined the message.
`005`	Expired during transmission	`expired`	The message was not delivered in time and expired before reaching the recipient.
`006`	Recipient network unavailable	`carrier_rejected`	The recipient’s network was unavailable or unresponsive.
`007`	Loop detected	`loop`	A message forwarding loop was detected.
`008`	Undeliverable	`carrier_rejected`	The recipient’s network did not accept the message.
`009`	Invalid message body	`invalid_content`	The message body was rejected. Review content for disallowed characters or formatting.
`010`	Campaign not registered	`unregistered_campaign`	The sending number is not attached to an approved campaign and cannot send to this recipient.
`011`	Too many requests	`rate_limited`	The message exceeded the allowed sending rate and was flagged as spam.
`012`	Invalid destination number	`invalid_destination`	The recipient’s number was rejected as invalid, deactivated, or unreachable.
`013`	Invalid sender number	`invalid_sender`	The sending number was rejected as invalid or improperly provisioned.
`014`	Expired in queue	`expired`	The message expired before it could be sent. Sending rate may exceed throughput capacity.
`015`	Blocked as spam (policy)	`blocked_as_spam`	The message was flagged by an internal spam policy and not delivered.
`016`	Daily sending limit reached (T-Mobile)	`rate_limited`	The campaign reached its daily T-Mobile sending limit. Limits reset at midnight Pacific.
`017`	Rejected as spam (AT&T)	`blocked_as_spam`	AT&T flagged the message content as spam. Review content and recipient consent.
`018`	Sending limit reached (AT&T)	`rate_limited`	The campaign exceeded AT&T’s per-minute sending limit.
`019`	Invalid campaign tag data (AT&T)	`unregistered_campaign`	AT&T rejected the message because campaign tagging information is incorrect.
`020`	Blocked - traffic inflation	`blocked_as_spam`	Suspected artificial 2FA traffic. Sending is blocked for 24 hours.
`021`	Destination is not a mobile phone	`landline_or_unreachable`	The account is set to mobile-only sending and the destination is not a mobile number.
`100`	Number not messaging enabled	`configuration`	The sending number is not enabled for messaging.
`150`	Toll-free number not in registry	`configuration`	The toll-free sending number is not listed in the voice registry and cannot be message-enabled.
`151`	Messaging enablement pending	`configuration`	Messaging is in the process of being enabled with another provider for this number.
`152`	Invalid registration parameter	`configuration`	A required registration parameter was missing or invalid.
`153`	Registry access denied	`configuration`	Could not access the messaging registry for this number.
`154`	Unauthorized network ID	`configuration`	Not authorized to use the network identifier associated with this number.
`155`	Authorization letter required	`configuration`	A Letter of Authorization is required to enable messaging on this number.
`156`	Unauthorized property	`configuration`	Not authorized to set one of the requested registration properties.
`157`	Temporarily blocked	`configuration`	Registry updates for this number are temporarily unavailable.
`158`	Delete failed	`configuration`	The record could not be found or deleted.
`159`	Registration error	`configuration`	An unknown error occurred while updating registration for this number.
`300`	Recipient opted out	`opted_out`	Recipient previously sent STOP (or similar) and cannot be messaged.
`301`	Unsupported message type	`invalid_destination`	The destination does not support this type of message or sender.
`302`	Message too large	`invalid_content`	The message exceeded the maximum number of allowed segments.
`303`	Message not found	`unknown`	The message record could not be located.
`304`	Invalid content combination	`invalid_content`	SMS requires a body; MMS requires a subject or media. Check message formatting.
`305`	Invalid sender address	`invalid_sender`	The sending number or sender ID is not valid for this messaging profile.
`306`	Alpha sender not configured	`invalid_sender`	No alphanumeric sender ID is configured on this messaging profile.
`307`	Alpha sender mismatch	`invalid_sender`	The provided alphanumeric sender ID does not match the configured one.
`308`	Invalid sender for MMS	`invalid_sender`	MMS can only be sent from US long-code or MMS-enabled short-code numbers.
`309`	Destination region not allowed	`configuration`	The destination region is not whitelisted on the messaging profile.
`310`	Invalid recipient address	`invalid_destination`	The recipient address was not a single valid number.
`311`	Invalid profile secret	`configuration`	The messaging profile secret provided was invalid.
`312`	Messaging profile disabled	`configuration`	The messaging profile is disabled. Re-enable it to resume sending.
`313`	Missing profile secret	`configuration`	The messaging profile secret was missing from the request.
`314`	Messaging disabled on account	`configuration`	Messaging has been disabled on this account.
`315`	Unhealthy sender number	`invalid_sender`	The sending number is temporarily restricted due to poor delivery performance or spam reports.
`316`	No content provided	`invalid_content`	The message had no body or media to send.
`317`	Invalid MMS content	`invalid_content`	MMS may contain up to 10 items and must be under 1 MB total.
`318`	Message queue full	`rate_limited`	The message queue is full. Reduce sending rate and retry.
`319`	Incompatible message type	`invalid_destination`	This combination of sender and recipient is not supported.
`320`	Sender temporarily unusable	`invalid_sender`	The sending number is temporarily unusable (e.g. still provisioning).
`321`	No usable numbers on profile	`configuration`	No usable sending numbers are assigned to this messaging profile.
`322`	Blocked due to content	`invalid_content`	The message contained disallowed content and was blocked.
`323`	Messaging activation failed	`configuration`	Messaging could not be enabled on the sending number.
`324`	Product type change failed	`configuration`	The number’s product type could not be changed.
`325`	Invalid alphanumeric sender ID	`invalid_sender`	The alphanumeric sender ID value is invalid.
`326`	Sender ID assignment failed	`configuration`	The alphanumeric sender ID could not be assigned to this profile.
`327`	Invalid link-shortener domain	`configuration`	The domain is not configured as a valid link-shortener domain.
`328`	SMS exceeds recommended size	`invalid_content`	The message would be split into too many SMS segments. Consider sending as MMS.
`329`	Toll-free number not verified	`unregistered_campaign`	The toll-free number has not completed use-case verification.
`330`	Toll-free number not provisioned	`configuration`	The toll-free number is not yet fully provisioned for messaging.
`331`	Missing whitelisted destinations	`configuration`	The messaging profile has no whitelisted destinations configured.
`332`	Brand cannot be deleted	`configuration`	The brand has an active campaign and cannot be deleted.
`333`	Profile spend limit reached	`rate_limited`	This send would exceed the messaging profile’s configured spend limit.
`41000`	WhatsApp error	`carrier_rejected`	The WhatsApp provider returned an error for this message.

Introduction

Webhooks

Endpoints

Code format

Categories

All error codes

​Code format

​Categories

​All error codes

Code format

Categories

All error codes