Understanding Message Failure Error Codes and Statuses

When a message fails to send or deliver, Telgorithm returns an error code describing why. This article lists all current error codes and what each one means. These codes are returned on the Outbound Message and via the OutboundMessageWebhook sent to the OutboundCallbackUrl configured on the Messaging Config.

General & sender errors (0-6)

Code	Meaning
0	No error
1	Sender phone number is invalid or undefined
2	Sender phone number doesn't belong to your company
3	Sender phone number doesn't belong to any TCR campaign
4	Sender phone number is not active yet
5	Sender phone number is in process of changing TCR campaign
6	Not all MNOs were selected on the currently attached TCR campaign. Please re-create the TCR campaign with all MNOs selected.

General & sender errors indicate a problem with the Telgorithm number or the attached campaign. Ensure that you're sending messages from numbers with an Active status that are connected to approved campaigns.

Recipient errors (1001-1007)

Code	Meaning
1001	Recipient phone number is invalid or undefined
1002	Message cannot be sent because the recipient has opted out
1003	Destination number is currently unable to receive text messages (no reception or handset off). Check with the end user.
1004	Destination address does not have text messaging services active
1005	Receiver's messaging provider likely does not support MMS. Check with the end user.
1006	Too many recipient phone numbers specified for group MMS (max 10 allowed)
1007	Recipients list contains duplicated elements

Recipient error codes relate to an issue with the recipient's mobile device. You can use the Carrier Lookup API to check if a specific phone number is able to receive texts.

Request & content errors (2001-2012)

Code	Meaning
2001	Text cannot be empty
2002	Text cannot be longer than 8000 characters
2003	Callback URL cannot be longer than 512 characters
2004	Expiration time provided with the request is in the past
2005	UTC date-time field in the request body was provided in an invalid format
2006	Both `to` and `recipients` fields are specified. Only one can be used.
2007	Conversation metadata is longer than 2048 characters
2008	Conversation metadata is not supported for group messages
2009	MediaUrls field contains an invalid and/or unreachable URL
2010	MediaUrls field can contain up to five items
2011	Some attachments referenced by MediaUrls exceed the maximum size limit
2012	Callback URL is badly formed, or its scheme is not HTTP nor HTTPS

Request & content errors indicate a technical issue with the message request itself. Simply correct the issue and retry.

Delivery & carrier errors (3001-3020)

Code	Meaning
3001	Message exceeds your Campaign Registry (TCR) MNO-approved throughput limit. The limit is too low to accommodate a single message.
3002	SPAM blocking: volume/velocity policies reached and content filtering
3003	Equivalent to "not authorized," usually because the number does not have SMS enabled
3004	Temporarily unable to deliver. Retry or check with the end user.
3005	Message queue full
3006	Message submitting failed
3007	Priority is wrong
3008	Destination address does not accept messages from toll-free numbers
3009	Message is too long for the receiving provider
3010	Source phone number may not be configured correctly (also possible upstream carrier outage)
3011	Network error between aggregator & MNO. Please contact support for further details.
3012	Destination number is out of carrier funds for texting (possibly a prepaid user). Check with the end user.
3013	Message flagged due to a non-compliant URL
3014	Temporary toll-free failure, likely due to a maintenance update. Please retry a bit later.
3015	TCR campaign the sender number belongs to is suspended by the MNO
3016	TCR campaign the sender number belongs to is not yet approved by the DCA
3017	TCR campaign the sender number belongs to has expired or has not been shared with Telgorithm
3018	TCR campaign the sender number belongs to is in an erroneous state. Contact support if this persists.
3019	Your Telgorithm account has insufficient funds and has been suspended
3020	Throughput allowance reached, likely due to unregistered traffic. Please resend or await full campaign approval.

Delivery & carrier errors are the most likely ones you may see. They indicate an upstream issue either at the DCA or carrier level, or with the recipient's handset itself. Check that the recipient's phone can receive messages, that you're not using a shortened URL or one unassociated with the campaign, and retry the message.

Unknown errors

Code	Meaning
2147483647	Unknown error

"Unknown error" means the DCA returned an error code which we have not yet mapped. Try the message again, and reach out to us if it continues to fail: support@telgorithm.com

Upstream carrier status (DcaStatus)

In addition to the Telgorithm error codes above, we surface the raw status reported by our upstream delivery partner directly, in the DcaStatus object on a message:

providerId: abstract provider identifier
code: provider-specific status or error code
name: provider-specific symbolic status/error name
description: human-readable description from the provider

This is the unified delivery status reported by the DCA (upstream partner), separate from the Telgorithm-level error codes above. Use it for the provider's own view of why a message failed.

If you have any questions about the error codes you've received, reach us at: support@telgorithm.com

Message statuses

Every outbound message also carries a status, separate from the error codes above:

Status	Meaning
Queued	The message is on hold, either due to Smart Queueing for carrier throughput limits, or because of the `SendingTimes` configured for the message.
Sent	The message has been sent and received by the DCA. This is a strong signal, but not a delivery guarantee. Messages can occasionally remain in `Sent` even after reaching the end user.
Delivered	The DCA has confirmed the message was successfully handed off to the carrier and delivered to the recipient's phone.
Failed	The message was not delivered, for one of the reasons in the error code tables above. It can fail before being sent to the DCA (no charge, since it was never sent), or fail further upstream at the DCA, carrier, or recipient's handset (charged, since it was processed upstream).
Expired	The message was sitting in a carrier throughput or `SendingTimes` queue and passed its expiration time, set via the `ExpiresOn` field.

Only Failed and Expired mean the message did not reach the recipient. Queued, Sent, and Delivered are all normal, non-error states in a message's lifecycle.