Telnyx Messaging Error Codes

This article provides a breakdown of the messaging error codes used by Telnyx and their meanings!

Alex Conroy avatar
Written by Alex Conroy
Updated over a week ago

At Telnyx, with the diverse array of messaging use cases and scenarios, we recognize the challenges in identifying the exact issue when a message attempt fails. Given the myriad potential situations, we realized the importance of offering our customers unique error codes. This approach offers a clear perspective on troubleshooting potential issues.

This article aims to shed light on possible error codes you may come across, assisting you in troubleshooting and finding workarounds for any issues.


What are the Messaging Error Codes?

Invalid Request Responses

These 1XXXX error codes suggest that there might have been an issue with the message request's formatting, and as a result, they do not exit the Telnyx platform. Fortunately, rectifying these are typically straightforward.

10001 - Inactive phone number

The phone number specified in the request is not active. If you believe otherwise, consider contacting the recipient's carrier.

10002 - Invalid phone number

The phone number mentioned in the request is invalid.

10003 - Invalid URL

The provided URL is either invalid, improperly structured, or exceeds the length limit. Please note, URLs can be up to 2000 characters long.

10004 - Missing required parameter

There's a missing required parameter. Refer to the error's source field to identify the missing information. For instance, is the "to" number absent?

10005 - Resource not found

The desired resource or URL was not located. Ensure you're using the appropriate endpoint.

10006 - Invalid ID

The supplied resource ID is not valid. Double-check if you have the necessary permissions to send SMS with your API key.

10007 - Unexpected error

An unforeseen issue arose, potentially on our side. Kindly reattempt and check our status page for any extensive SMS problems on our platform.

10009 - Authentication failed

The mandatory authentication headers were either incorrect or omitted. Make sure to include accurate API keys in your Authorization header.

10010 - Authorization failed

You lack the permissions for the requested action on the given resources. This error is akin to 10009 and 10006. You might need to get in touch with your organization's owner for SMS sending permissions or for using specific features.

10011 - Too many requests

Your requests have exceeded the limit. Ensure your API requests adhere to the prescribed rate. To prevent surpassing the limits, we advise monitoring and controlling the rate of requests from your application. Our developer documentation clearly states the API rate limits.

10015 - Bad Request

The request was unsuccessful due to improper formatting. Make sure your messages align with our stipulated request format. For further details, consult our API messaging guide.

10016 - Phone number must be in +E.164 format

The phone number should be in the +E.164 format.


Account Level Errors

These 2XXXX error codes point to potential issues with the account details provided or the account responsible for sending the SMS. It might be necessary to contact your organization's owner or Telnyx support for guidance.

20002 - API Key revoked

The API Key specified in your authorization header isn't active. Visit the API Keys section in your Mission Control Portal to ensure the used API key is enabled.

20006 - Expired access token

The given access token has expired. Check if your API v1 token remains valid. We also encourage migrating to our enhanced API v2!

20012 - Account inactive

Your request can't be processed because your account has been deactivated, possibly due to insufficient funds. Please top up your account and try again.

20013 - Account blocked

Your account is blocked. Should this appear to be a mistake, please get in touch with Telnyx support.

20014 - Account unverified & 20016 - Account not level 1 verified

You need to validate your account using a mobile phone number to activate messaging.

20015 - Feature not enabled

SMS functionality isn't activated for your account. Reach out to Telnyx customer support for more details.

20017 - Account not level 2 verified

Your account hasn't achieved level 2 verification and therefore can't execute the desired action. Level 2 verification necessitates reaching out to Telnyx and is essential for sending messages using alphanumeric sender IDs.

20100 - Insufficient Funds

Add the necessary funds to your account to dispatch your intended messages.


Delivery Errors

These 4XXXX 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 is either a landline or a non-routable wireless number and doesn't have messaging capabilities.

40002 - Blocked as spam - Temporary

SPAM filter flagged the message. Temporarily halt sending and reassess your recipients to ensure their consent.

40003 - Blocked as spam - Permanent

SPAM filter flagged the message, permanently blocking the originating number. Avoid this by ensuring recipients' consent. Contact Telnyx support if inaccurately flagged.

40004 - Rejected by destination

The recipient's server declined the message. Seek assistance from Telnyx support or the recipient carrier.

40005 - Message expired during transmission

The message wasn't delivered timely. If persistent, reach out to Telnyx support.

40006 - Recipient server unavailable

The recipient's server is non-responsive. If the issue persists, contact Telnyx support.

40008 - Undeliverable

The recipient carrier rejected the message due to various potential reasons.

40009 - Invalid message body

The message body doesn't align with certain carrier rules, leading to rejection. Please refer to Telnyx's Acceptable Use Policy.

40011 - Too many requests

Exceeded the upstream rate limit, flagging the message as SPAM. Adjust your messaging rate as per your account's throughput.

40012 - Invalid messaging destination number

The destination phone number was rejected by the carrier. Potential reasons include:

  • The number is unowned.

  • The number is deactivated.

  • The recipient lacks credit.

  • The recipient cannot receive short codes (for short code messaging only).

40013 - Invalid messaging source number

Your source phone number was declined by the carrier. Ensure your number is correctly provisioned; if uncertain, contact Telnyx support.

40014 - Message expired in queue

The message expired before being relayed by Telnyx. You won't be billed for this. This occurs if your messaging rate surpasses your available SMS throughput.

40015 - Blocked as spam - internal

The message was flagged by Telnyx's internal SPAM filter. Please adhere to the Acceptable Use Policy for Messaging.

40100 - Number not messaging enabled

Ensure the number has messaging capabilities and an assigned messaging profile on the Telnyx platform.

40150 - Toll free number not in registry

Ensure you register your toll-free number since it's not in the voice registry.

40151 - Message enablement pending with other provider

The number is being enabled by another messaging provider.

40300 - Blocked due to STOP message

You can't send messages to the destination since they've sent a STOP message to you. Make sure to vet your recipient list. Keywords triggering this block include:

  • CANCEL

  • END

  • QUIT

  • STOP (and its variants)

  • UNSUBSCRIBE

40301 - Unsupported message type for the 'to' address

The requested destination doesn't support the type of message or sender.

40302 - Message too large

SMS exceeding 140 bytes are divided into multiple parts. Depending on content, 34 to 153 characters fit in each segment.

40304 - Invalid combination of message content arguments

SMS needs a body field; MMS requires either subject or media_urls. Check the support docs for message formatting.

40305 - Invalid 'from' address

The sender must be a valid phone number, short code, or alphanumeric sender ID related to the active messaging profile. If you have enabled number pooling and skip unhealthy numbers on your messaging profile, this error can also occur. This is because Telnyx will remove numbers from the pool if we detect that 75% or more of messages are being marked as spam.

40306 - Alpha sender not configured

Update your profile to use an alphanumeric sender ID.

40308 - Invalid 'from' address for MMS

Ensure the 'from' number can send MMS messages.

40309 - Invalid destination region

Ensure the destination region is whitelisted in your messaging profile.

40310 - Invalid 'to' address

The recipient address must be valid.

40311 - Invalid messaging profile secret

Ensure the correct X-Profile-Secret header is provided.

40312 - Messaging profile is disabled

Activate your messaging profile in the portal settings.

40313 - Missing messaging profile secret

Ensure the X-Profile-Secret header is included.

40314 - Messaging disabled on account

If not self-requested, contact Telnyx support.

40315 - Unhealthy 'from' address

The sending number failed a health check due to low deliverability or high spam rates.

40316 - No content provided for message

Provide the necessary fields for either SMS or MMS.

40317 - Invalid MMS content

MMS can have up to 10 URLs and be under 1 MB. Refer to Telnyx's FAQ for MMS guidance.

40318 - Message queue full

Monitor and adjust your message rate according to the throughput guide.

40319 - Incompatible message type for the 'to' address

Ensure compatibility between the sender type and the recipient.

40320 - Temporarily unusable 'from' address

Wait until the number's purchase is finalized for it to be usable.

40321 - No usable numbers on messaging profile

If using number pooling, assign numbers to your messaging profile.

40322 - Blocked due to content

Refer to the Acceptable Use Policy.

40328 - SMS exceeds recommended size

For extended messages, consider sending as MMS.

40329 - Toll free number not yet verified

A use case verification request has not yet been submitted for the number or the request is still pending. Please submit a use case verification request for the toll free number or wait for approval on the request.


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:

40016 - T-Mobile 10DLC Sending Limit Reached

  • Explanation: 10DLC (10-Digit Long Code) is a system used by carriers like T-Mobile to manage and regulate A2P (Application-to-Person) SMS traffic. Each brand is assigned a certain throughput limit based on their brand score. This error indicates that you've exceeded the daily message sending limit set by T-Mobile for your brand. The count gets reset every day at midnight PST.

  • Solution: Either wait for the count to reset at midnight PST or review the throughput limits related to your brand score in Telnyx's FAQ to understand the imposed restrictions.

40017 - AT&T 10DLC Spam Message Rejected

  • Explanation: AT&T has identified the content of your message as spam when sent via the 10DLC route. This could be due to various reasons such as the content resembling known spam patterns or the lack of proper opt-in from the message recipients.

  • Solution: Review the content of your message to ensure it doesn't violate any spam guidelines. Make certain that you have appropriate permissions (opt-ins) from all recipients before sending messages. This ensures compliance with best practices and reduces the chances of your messages being flagged.

40018 - AT&T 10DLC Sending Limit Reached

  • Explanation: Similar to the T-Mobile error, this indicates that you've reached AT&T's sending limit for your brand on the 10DLC route. AT&T's sending limit is given in message parts per minute. This error means that the total number of messages from this campaign has exceeded this limit for this given minute. This limit is influenced by the brand score assigned to your brand.

  • Solution: Limit the amount of messages sent per minute by your campaign. Refer to Telnyx's FAQ to get a deeper understanding of the throughput limits based on your brand score.

Did this answer your question?