> ## Documentation Index > Fetch the complete documentation index at: https://docs.politicalcomms.com/llms.txt > Use this file to discover all available pages before exploring further. # Delivery Error Codes > Every error_code the message.failed webhook can deliver, with its error_message and what to do about it. When a message fails, the [`message.failed`](/api-reference/webhooks/events#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](mailto:support@politicalcomms.com) with the code and the `message_id` and we will investigate. ## Categories Every code belongs to a category that tells you how to react: | 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. |