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.

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.

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

The phone number mentioned in the request is invalid.

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

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?

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

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

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

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

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.

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.

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.

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

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.

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.

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

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.

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

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

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

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.

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

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.

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.

The destination is either a landline or a non-routable wireless number and doesn't have messaging capabilities.

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

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

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

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

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

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

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

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

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

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

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.

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

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

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

The number is being enabled by another messaging provider.

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:

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

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

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

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.

Update your profile to use an alphanumeric sender ID.

Ensure the 'from' number can send MMS messages.

Ensure the destination region is whitelisted in your messaging profile.

The recipient address must be valid.

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

Activate your messaging profile in the portal settings.

Ensure the X-Profile-Secret header is included.

If not self-requested, contact Telnyx support.

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

Provide the necessary fields for either SMS or MMS.

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

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

Ensure compatibility between the sender type and the recipient.

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

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

Refer to the Acceptable Use Policy.

For extended messages, consider sending as MMS.

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.

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: