Errors

Click here to read our full message deliverability guide.

When you send a message using the /message/send route, the message delivery may later fail with an error code even if the initial request received a 200 response. This is because the response only indicates that the message was succesfully queued for sending with our downstream SMS provider and the cell carriers. The message delivery can fail for a number of reasons. You can track the delivery status of each message by navigating to the Messages tab on your dashboard and viewing the logs, or by using webhooks to be notified of delivery status changes for each message.

Message statuses

A message stuck in SENT status almost always means it was delivered.

Status	Description
`CREATED`	Message has been created and will be queued for sending.
`QUEUED`	Message is queued and is expected to be sent shortly.
`SENT`	Message has been successfully sent to the recipient.
`DELIVERED`	Delivery receipt has been received (sometimes inconsistent).
`FAILED`	Message failed to be delivered. See list of codes below.
`SCHEDULED`	Message is queued for sending at the `scheduledTime`

Failure codes

When a message delivery fails, the status field of the message will be set to FAILED and the errorCode field will be set to one of the following error codes:

Don’t be intimidated by this long list. You won’t see most of these errors :)

Code	Description
`1002`	Please check to make sure you have the correct recipient address/format in your “to” address.
`1005`	Subscriber has not consented to receive the message.
`1007`	Message could not be sent within the expiry time defined. Please resend the message.
`1009`	Destination device is unreachable. If the error persists, please contact us. (see more)
`1010`	File refused. Please retry after selecting a different mimetype for your MMS file.
`1012`	Message size exceeds max allowed size. Please retry after reducing the message size.
`1014`	Message encoding failed. Please retry after fixing the unsupported message contents.
`1016`	Invalid/illegal character in URL. Please retry after removing illegal characters in the url.
`1019`	Attachment size exceeds max allowed size. Please retry after reducing the attachment size.
`1026`	Too many recipients. Please retry after reducing the number of recipients.
`1030`	Too many recipients in one batch. Please retry after reducing the recipients in the batch.
`1038`	Outgoing queue is full. Please contact support.
`1039`	The message exceeds throttling limit. If the error persists on retry, please contact support.
`1040`	Invalid scheduled delivery time. Please retry message after fixing the schedule delivery time.
`1043`	Destination address is invalid. Please retry after fixing the destination address.
`1046`	Message was rejected. Please contact support.
`1047`	Permission denied. Please contact support.
`1049`	Invalid request. Please contact support.
`1051`	Message validation failed. Please contact support.
`1053`	Failed to upload media URL. If the error persists on retry, please contact support.
`1054`	Failed to download media URL. If the error persists on retry, please contact support.
`1056`	Recipient number is deactivated. Please change recipient number and retry.
`1058`	Message scheduled time too far ahead. Please change Message Schedule time and retry.
`1059`	Message request timed out. Please contact support.
`1062`	Daily quota restriction violation. If the error persists on retry, please contact support.
`1065`	Message restricted by upstream provider. Please contact support.
`1203`	Temporary failure reaching recipient. If the error persists on retry, please contact support.
`1310`	Recipient has unsubscribed from messages from your campaign (i.e. by texting STOP).
`1320`	You have reached your (see more).
`1330`	Message blocked by upstream provider. Please contact support.
`1340`	Messaging exceeded (see more).
`1350`	Phone number is invalid or inactive (cannot receive text messages).
`1360`	Phone number is a landline (cannot receive text messages).
`4XXX`	Internal server error. Please contact support.

API Reference

Message

Brand

Campaign

Number

Webhook

Message statuses

Failure codes

​Message statuses

​Failure codes

Message statuses

Failure codes