> ## 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. `"10011"`, `"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. See [Carrier throughput limits](/api-reference/best-practices#carrier-throughput-limits). |
| `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 destination is not a mobile number, and only mobile numbers can be messaged. |
| `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 sending configuration. |
| `306` | Alpha sender not configured | `invalid_sender` | No alphanumeric sender ID is configured for this sending configuration. |
| `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 allowed by the sending configuration. |
| `310` | Invalid recipient address | `invalid_destination` | The recipient address was not a single valid number. |
| `311` | Invalid sending credentials | `configuration` | The sending credentials provided were invalid. |
| `312` | Sending configuration disabled | `configuration` | The sending configuration is disabled. Re-enable it to resume sending. |
| `313` | Missing sending credentials | `configuration` | The sending credentials were missing from the request. |
| `314` | Sending temporarily unavailable | `configuration` | Sending is temporarily unavailable for this number. No action is needed on your end - support has been alerted. |
| `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 sending numbers | `configuration` | No usable sending numbers are assigned to this sending configuration. |
| `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 sending configuration has no allowed destinations configured. |
| `332` | Brand cannot be deleted | `configuration` | The brand has an active campaign and cannot be deleted. |
| `333` | Spend limit reached | `rate_limited` | This send would exceed the configured spend limit. |
| `10011` | Sending rate exceeded | `rate_limited` | The message was submitted faster than the allowed sending rate. It is retried automatically; this code is terminal only when retries were exhausted. |
| `41000` | WhatsApp error | `carrier_rejected` | The WhatsApp provider returned an error for this message. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.