At Telnyx, with such a broad range of messaging use cases and situations, we understand if it can be difficult to pinpoint what exactly went wrong if your message attempt fails. With so many potential situations we realised that in order to help our customers achieve their best deliverability on our platform we needed to provide them unique error codes to give a clear overview on how to troubleshoot any potential headaches.

This article is aimed at providing an insight into potential error codes you may encounter with the goal of helping you troubleshoot and workaround any snags.

Messaging Error Codes

Invalid Request Responses

These error codes indicate there was a potential issue with how the message request was formatted and do not leave the Telnyx platform. Luckily these are usually quite simple fixes!

10001 - Inactive phone number	The phone number provided in the request is inactive. If this is not the case you may need to reach out to the recipient carrier.
10002 - Invalid phone number	The phone number provided in the request is invalid.
10003 - Invalid URL	The URL provided was invalid, malformed, or too long. URLs can be a maximum of 2000 characters.
10004 - Missing required parameter	A required parameter was missing. Consult the source field on the returned error to determine the missing field - for example is the "to" number missing?
10005 - Resource not found	The requested resource or URL could not be found. Are you sure you are sending using the correct endpoint?
10006 - Invalid ID	The resource ID provided was invalid. Please check that you have authorization to send SMS using your API key
10007 - Unexpected error	An unexpected error occurred. This may be the result of a temporary issue on our end. Please retest and check our status page to see if there is any widespread SMS issues on our platform.
10009 - Authentication failed	The required authentication headers were either invalid or not included in the request. Please ensure you are including valid API keys in your Authorization header.
10010 - Authorization failed	You do not have permission to perform the requested action on the specified resource or resources. Similar to 10009 and 10006, you may need to reach out to your organisation owner to request permission to send SMS or to use campaign or brand features
10011 - Too many requests	You have exceeded the maximum number of allowed requests. Please ensure you are sending API requests within the allotted rate limit. To avoid exceeding the limits we recommend that you proactively limit the rate of requests made by your application. API rate limits are documented here in our developer docs.
10015 - Bad Request	The request failed because it was not well-formed. Have you ensured your messages are in line with our provided request format? Please see our API messaging guide for reference.
10016 - Phone number must be in +E.164 format	The specified phone number parameter must be in +E.164 format.

Account Level Errors

These error codes indicate there was a potential issue with the account information provided or the account sending these SMS. You may need to reach out to your organisation owner or Telnyx support for assistance!

20002 - API Key revoked	The API Key provided in your authorization header is not active. Please navigate to the API Keys section of your Mission Control Portal to ensure the API key used is toggled on.
20006 - Expired access token	The access token provided is expired. You may need to check your API v1 token is still valid. We also recommend switching to our new and improved API v2!
20012 - Account inactive	The request cannot be fulfilled because your account has been deactivated. This may be due to lack of funds in your account. Please add funds to your account and retest.
20013 - Account blocked	Your account has been blocked. Please reach out to Telnyx support if this response is in error.
20014 - Account unverified and 20016 - Account not level 1 verified	You will need to verify your account using a mobile phone number in order to enable messaging.
20015 - Feature not enabled	SMS is not enabled for your account. Please contact Telnyx customer support for more information.
20017 - Account not level 2 verified	The account has not been level 2 verified, and cannot perform the requested action. Level 2 verification requires contacting Telnyx, and is required to send messages from alphanumeric sender IDs
20100 - Insufficient Funds	Please add the required funds to your account to send the desired messages.

Delivery Errors

These error codes indicate there was an issue when delivering the sent SMS to your desired recipient. This information can be received from downstream and recipient carriers so it is important to vet your use case and messaging content to ensure deliverability. The following support article can be a handy troubleshooting guide for many of these issues: SMS Long Code Deliverability Best Practices.

Some Important Key Points:

It is important to note that messages that fail due to the message failing off the Telnyx network will result in charges as they have left the Telnyx network.
Often carriers can block messaging from Toll-Free numbers if the messaging has not been registered. To get started with Toll-Free messaging it is necessary to have you use case registered due to the high risk of fraud carriers face from this form of messaging. Please see our support article for Toll-Free messaging for instructions on how to achieve this.

40001 - Not Routable	The destination number is either a landline or a non-routable wireless number and does not have messaging capabilities.
40002 - Blocked as spam - Temporary	The message was flagged by a SPAM filter and was not delivered. This is a temporary condition. We recommend pausing sending this message and retesting as well as vetting your recipients list to ensure they are opted in to receive your messages.
40003 - Blocked as spam - Permanent	The message was flagged by a SPAM filter and was not delivered. The originating phone number is permanently blocked. This occurs due to issues with prior messaging on your account. The best practice to avoid this is vetting your recipients list to ensure they are opted in to receive your messages. Please contact Telnyx support if you believe this to be an error.
40004 - Rejected by destination	The recipient server is rejecting the message for an unknown reason. Please contact Telnyx support or the recipient carrier for assistance.
40005 - Message expired during transmission	The message expired before it could be fully delivered to the recipient. This error occurred after the message left Telnyx and was en-route to the destination. Please contact Telnyx support for assistance if this persists.
40006 - Recipient server unavailable	The recipient server is unavailable or not responding. This may be a temporary issue. If the error persists, contact Telnyx support.
40008 - Undeliverable	The recipient carrier did not accept the message. This is a general purpose undeliverable message. This can be caused if the destination does not have messaging service, or their account may not be in good standing. It can also occur if the destination network may be experiencing a temporary problem.
40009 - Invalid message body	The message body was invalid. The rules Telnyx uses to allow messages may not align with all carriers at all times. If the destination carrier uses more stringent rules, they may reject messages. Please see our Acceptable Use Policy for Messaging as a guide.
40011 - Too many requests	Exceeded upstream rate limit. As a result the message was flagged by a SPAM filter and was not delivered. This is a temporary condition. Please ensure your messaging rate is in line with your account throughput.
40012 - Invalid messaging destination number	The destination phone number was deemed invalid by the carrier and was rejected. Potential causes include: The number is not owned. The number has been deactivated. The recipient does not have credit to receive messages. The recipient can not receive short codes (short code messaging only).
40013 - Invalid messaging source number	The source phone number was deemed invalid by the carrier. This can potentially be a result of your number not having been correctly provisioned and we recommend you reach out to Telnyx support for assistance.
40014 - Message expired in queue	The message expired in the queue. This error occurred before Telnyx attempted to relay your message, and you were not billed. Messages are queued if your messaging exceeds your available SMS throughput.
40015 - Blocked as spam - internal	The message was flagged by an internal Telnyx SPAM filter. Please ensure you are meeting our Acceptable Use Policy for Messaging and avoiding SPAM to the same recipients.
40100 - Number not messaging enabled.	The number is not currently messaging enabled on the Telnyx platform. Please ensure this number is messaging capable and has an assigned messaging profile.
40150 - Toll free number not in registry	Messaging cannot be enabled for this number because the number is not in the voice registry. Please make sure to register your toll free number.
40151 - Message enablement pending with other provider	Messaging is in the process of being enabled with another messaging provider.
40300 - Blocked due to STOP message	Messages cannot be sent from your number to a destination number because the destination has sent your number a stop message. Please make sure to vet your list of recipients. Stop messages are those that consist solely of one of the following words (case and whitespace insensitive): CANCEL END QUIT STOP STOPALL STOP ALL UNSUBSCRIBE
40301 - Unsupported message type for the 'to' address	The requested destination is currently unsupported for the type of traffic originated by the sender or sending number. Messages from long codes or toll free numbers, including multimedia messages, can only be sent to US and Canadian destinations. For other destinations, consider using an alphanumeric sender.
40302 - Message too large	SMS messages over 140 bytes are split into multiple parts. Depending on the encoding and characters, anywhere from 34 (emojis) to 153 (ASCII) characters can fit in each part.
40304 - Invalid combination of message content arguments	To send an SMS, the body field must be provided, and it must not be an empty string. To send an MMS, the subject and/or media_urls fields must be provided. Please see our support docs for further information on message format here.
40305 - Invalid 'from' address	A valid from field must be specified. The value must be a string containing a valid phone number in +E.164 format, a short code, or an alphanumeric sender ID associated with the sending messaging profile. Please ensure the 'from' number is assigned to the messaging profile in use. Alphanumeric sender IDs must be between 1 and 11 characters long, and can only contain ASCII letters, numbers, and spaces. They must contain at least one letter.
40306 - Alpha sender not configured	The messaging profile is not configured with an alphanumeric sender ID. To send a message from an alphanumeric sender ID, the messaging profile must be configured with the desired sender. Update your messaging profile and try again. This can be done using the messaging profile settings in your mission control portal or using the API.
40308 - Invalid 'from' address for MMS	MMS can only be sent from US long code phone numbers, MMS-configured short-codes and most toll-free numbers. Please ensure the 'from' number is assigned to the messaging profile in use.
40309 - Invalid destination region	The region for destination number is not included in the messaging profile's list of whitelisted destinations. This list can be found in your messaging profile's outbound settings.
40310 - Invalid 'to' address	The 'to' address must be a valid number provided in +E.164 format or else a valid short code. If using API V2, either an array of length one, or a single string must be provided. Multi-destination messages are not currently supported.
40311 - Invalid messaging profile secret	The provided X-Profile-Secret header was not recognized as a valid messaging profile secret. This applies to messaging sent using API V1 and can be found in your messaging profile settings.
40312 - Messaging profile is disabled	The messaging profile is currently disabled. Please navigate to the messaging profiles section of your portal and ensure the profile is enabled.
40313 - Missing messaging profile secret	The X-Profile-Secret header was missing. This applies to messaging sent using API V1 and can be found in your messaging profile settings.
40314 - Messaging disabled on account	Messaging has been disabled on your account. This may have been disabled after a request from your account. Please contact Telnyx support if this is not the case.
40315 - Unhealthy 'from' address	A health check was requested on the sending number, which it failed to pass. Recent traffic data on the number is used to determine its outbound success and spam rejection rates. Health metrics per number are calculated on a regular basis, taking into account the deliverability rate and the amount of messages marked as spam by upstream carriers. If deliverability is below 25% or spam detection is over 75% then numbers will be considered unhealthy.
40316 - No content provided for message	To send an SMS, the text field must be provided, and it must not be an empty string. To send an MMS, the text and/or media_urls fields must be provided.
40317 - Invalid MMS content	Multimedia messages (MMS) can only contain up to 10 items (URLs listed in media_urls) and the total size must be less than 1 MB. For further information on MMS with Telnyx please see our FAQ on the topic.
40318 - Message queue full	This error is shown when your message queue is full and you attempt a new message. The queue limits the rate messages can be sent per account and per number. Please check our handy throughput guide for more details.
40319 - Incompatible message type for the 'to' address	It is not possible to send messages to the requested destination using the given sender or sending number. For example, messages cannot be sent from an alphanumeric sender ID to a short code. Please ensure the destination is capable of receiving the intended message type.
40320 - Temporarily unusable 'from' address	The specified number is configured for messaging, but it cannot yet be used to send messages. This is a temporary condition, which typically occurs because the number was recently purchased and the number order has not yet completed. Please wait for the purchase to be finalized, at which time the number will become available for use. If this error is consistent after the purchase is finalized please reach out to Telnyx support for assistance.
40321 - No usable numbers on messaging profile	If you are using number pooling to send your messages please ensure the messaging profile in use has numbers assigned to it. Further information on number pooling can be found here.
40322 - Blocked due to content	Certain content can cause a message to be rejected. Please see our Acceptable Use Policy for reference.
40328 - SMS exceeds recommended size	SMS messages over 140 bytes are split into multiple parts. Depending on the encoding and characters, anywhere from 34 (emojis) to 153 (ASCII) characters can fit in each part. Messages over a certain number of parts are better sent as MMS messages.

10DLC Messaging Delivery Errors

These error codes indicate there was an issue when delivering the sent SMS using either our 10DLC product. The following support articles can be a handy troubleshooting guide for many of these issues:

Frequently Asked Questions about 10DLC

40016 - T-Mobile 10DLC Sending Limit Reached	You have exceeded T-Mobile's daily allotted throughput for the brand associated to this phone number. The count resets at midnight PST. Messaging throughput is dependent on the Brand Score of the Brand and is detailed in our FAQ.
40017 - AT&T 10DLC Spam Message Rejected	AT&T has rejected your message for spam on the 10DLC route. Please check the content of your message and ensure you have obtained opt-ins for your senders.
40018 - AT&T 10DLC Sending Limit Reached	You have exceeded AT&T's daily allotted throughput for the brand associated to this phone number. The count resets at midnight PST. Messaging throughput is dependent on the Brand Score of the Brand and is detailed in our FAQ.