From 96b59c33dacb7fcfd29948f420bc37ed50778ab5 Mon Sep 17 00:00:00 2001 From: manny-r31 Date: Thu, 23 Oct 2025 08:51:38 -0400 Subject: [PATCH 1/2] cXML error code refresh --- .../overview/error-codes.mdx | 755 +++++++++++++++++- 1 file changed, 713 insertions(+), 42 deletions(-) diff --git a/website/docs/main/rest/compatibility-api/overview/error-codes.mdx b/website/docs/main/rest/compatibility-api/overview/error-codes.mdx index c630a45ce..bfb938708 100644 --- a/website/docs/main/rest/compatibility-api/overview/error-codes.mdx +++ b/website/docs/main/rest/compatibility-api/overview/error-codes.mdx @@ -1,46 +1,717 @@ --- -title: Error Codes +title: Error codes +slug: /rest/compatibility-api/overview/error-codes sidebar_position: 1 --- -# Error Codes - -The API defines error codes to convey information about the possible issues. -They are either generic or specific to an interaction mode (voice or messaging). - -| Code | Type | Message | -|:-------------------------------------------------------------------|:----------|:--------------------------------------------------------------------------------------------------------------------------------------------| -| 10001 | Generic | Space is not enabled to use requested feature | -| 10003 | Generic | API tokens can only have the following permissions: calling, chat, fax, management, messaging, numbers, pubsub, storage, tasking, and video | -| 10004 | Generic | The subproject ID provided cannot be found or does not belong to the project used to authenticate the request. | -| 11200 | Generic | HTTP Retrieval Failure | -| 11751 | Generic | MMS -> Media exceeds mobile operator size limit | -| 12100 | Generic | Document Parse Failure | -| 12300 | Generic | Invalid Content-Type | -| 13221 | Generic | Dial -> Number: Invalid Method Value | -| 21210 | Generic | 'From' phone number not verified | -| 21212 | Generic | Phone number is not in the correct format. Please use E.164 format, i.e. +15558675309 | -| 21217 | Generic | A call or SMS is placed to a destination which does not represent a valid phone number | -| 21219 | Generic | 'To' phone number not verified | -| 21601 | Generic | From number is not an SMS-capable phone number. | -| 21602 | Generic | Message body is required | -| 21603 | Generic | The source 'From' phone number is required to send an SMS | -| 21604 | Generic | The destination 'To' phone number is required to send an SMS | -| 21610 | Generic | Attempt to send to unsubscribed recipient | -| 21611 | Generic | This 'From' number has exceeded the maximum number of queued messages | -| 21617 | Generic | The concatenated message body exceeds the 1600 character limit | -| 21620 | Generic | Invalid media URL(s) | -| 21623 | Generic | Number of media files exceeds allowed limit | -| 63019 | Generic | Media Failed to Download | -| 21717 | Messaging | Number must be assigned to a Campaign to send US traffic | -| [30002](/messaging/getting-started/how-to-troubleshoot-common-messaging-issues#30002) | Messaging | Account suspended | -| [30003](/messaging/getting-started/how-to-troubleshoot-common-messaging-issues#30003) | Messaging | Unreachable destination handset | -| 30004 | Messaging | Message blocked or opted out | -| [30005](/messaging/getting-started/how-to-troubleshoot-common-messaging-issues#30005) | Messaging | Unknown destination handset | -| [30006](/messaging/getting-started/how-to-troubleshoot-common-messaging-issues#30006) | Generic | Landline or unreachable carrier | -| [30007](/messaging/getting-started/how-to-troubleshoot-common-messaging-issues#30007) | Messaging | Message marked as spam | -| [30008](/messaging/getting-started/how-to-troubleshoot-common-messaging-issues#30008) | Messaging | Unknown error | -| 30010 | Messaging | Message price exceeds max price | -| [30022](/messaging/getting-started/how-to-troubleshoot-common-messaging-issues#30022) | Messaging | Campaign Registry Throughput Limit Exceeded | -| 30027 | Messaging | T-Mobile Daily Message Limit Reached | -| 53603 | Messaging | Internal failure while processing media | +import APIField from "@site/src/components/APIField"; + +# Error codes + +The API defines error codes to convey information about possible issues. +Below is a list of all error codes as well as possible causes for the error code to appear. + +## Errors + + + +- The provided list of capabilities contains invalid capabilities for the phone number +- The capabilities for the phone number are missing + + + + + +- The fee for the operation you are trying to perform costs more than the available balance + + + + +- The argument passed is invalid +- An attempt was made to cancel an in-progress call +- An attempt was made to update a completed call +- An attempt was made to update a conference or conference participant for a completed conference +- An attempt was made to cancel an in-progress or finished fax +- A required argument was left blank +- An attempt was made to redact a message that is still in-progress + + + + + +- The operation attempted is not enabled on the space + + + + + +- The permissions passed for the API token contain invalid selections + + + + + +- The subproject ID passed does not belong to the project used to authenticate the request + + + + + +- The URL passed to update the queue member is invalid + + + + + +- The attempt to deliver a webhook to your server timed out + + + + + +- The attempt to deliver a webhook to your server responded with a 4xx or 5xx status code + + + + +- The total size of the media message request exceeds the maximum size limit + + + + + +- Your CXML document failed to parse. There could be a leading space, a missing or unclosed element, or incorrect attribute + + + + + +- The content type of the provided URL is invalid + + + + + +- The HTTP method attribute is invalid - it can only be 'GET' or 'POST' + + + + + +- The attribute in sendDigits includes an invalid character. It may only contain '0123456789ABCD*#wW' + + + + + +- The provided event is not a valid recording callback event + + + + + +- The provided trim value for the recording is invalid + + + + + +- The provided conference attributes are invalid +- The required conference attributes are missing +- The participant to be coached is not in the provided conference + + + + + +- An unknown error occurred + + + + + +- The friendly name is missing +- The friendly name must be between 1 and 64 characters long +- The friendly name is invalid + + + + + +- There was an authentication error or API access is blocked for this feature + + + + + +- An attempt was made to delete a call that is not finished +- An attempt was made to delete a fax that is not finished +- An attempt was made to delete a message that is in-progress +- An attempt was made to delete media for a message that is in-progress + + + + + +- The action you are attempting to performed is disabled for the account + + + + + +- The resource you are trying to access does not exist + + + + + +- The passed document is not a valid CXML document. The CXML document is missing a content type header or contains an invalid parameter/value + + + + + +- There were too many requests or throughput was exceeded + + + + + +- An internal error occurred + + + + + +- A phone call was attempted without a CXML Url or ApplicationSid + + + + + +- The provided Timeout parameter was invalid +- The provided Timeout parameter was not a positive whole integer + + + + + +- The Method parameter provided was not GET or POST + +- The passed mode was not valid for the phone number + + + + + +- The From number provided was not a purchased or verified number in your project +- The From number provided was not a purchased number in your project +- An outbound message was attempted where the From number provided was a verified caller ID + + + + + +- The 'To' number provided was missing +- The 'To' number provided has an invalid format + + + + + +- The From number provided was not E164 while dialing to a phone number +- The From number provided must be a E164 number, caller ID string, or SIP URI +- The From number provided must be a E164 number or client identifier +- The From number provided has invalid format + + + + + +- An outbound call was attempted without a From number + + + + + +- The To phone number provided does not appear to be valid + + + + + +- The provided ApplicationSid is invalid +- The provided ApplicationSid does not exist + + + + + +- The account limitations for this feature have been exceeded +- The 'To' phone number is not a verified caller ID and the account is in Trial mode +- The 'To' phone number is not a verified caller ID as required for Platform Free Trial messaging + + + + + + +- The call cannot be redirected if it is not in-progress +- A stream cannot be started for a call or conference in the current state +- A recording cannot be started for a call that is not in-progress + + + + + +- The AMD parameters provided are not valid + + + + + +- The AMD status callback URL is missing + + + + + +- The phone number you're attempting to purchase has an invalid format + + + + + +- The URL is not valid +- The URL is not a fully qualified URL + + + + + +- The callback URL is not set + + + + + +- The passed VoiceApplicationSid or SmsApplicationSid could not be found + + + + + +- An area code or number must be provided to purchase a number + + + + + +- The area code is not formatted correctly + + + + + +- The supplied callback URL is not valid + + + + + +- An attempt was made to update a conference with an invalid status + + + + + +- The page token supplied was invalid + + + + + + +- The phone number is not a valid SMS or MMS capable number +- The phone number is not a voice capable number +- The phone number is not a fax capable number + + + + + +- An attempt was made to send a message without a media URL or text body + + + + + +- The format of the 'To' or 'From' is invalid +- The 'From' number is missing +- The 'To' number has invalid format +- The 'To' number is missing + + + + + +- The 'To' number is required to send a message + + + + + +- The 'To' number provided is not a mobile number + + + + + +- The message was blocked by the user or sent from a blacklisted number + + + + + +- The 'From' number has exceeded the maximum number of queued calls, messages, or faxes for the account + + + + + +- The Media provided is not supported + + + + + +- The 'To' number is not a valid mobile number + + + + + +- The concatenated message body exceeds the allowed character limit + + + + + +- The media URL(s) provided is/was invalid +- The URL must be HTTP or HTTPS + + + + + +- The number of media files exceeds the allowed limit + + + + + +- The validity period provided is invalid + + + + + + +- The callback event is not valid + + + + + +- The E911 address provided is invalid for this phone number + + + + + +- The number group provided is invalid or unrecognized + + + + + +- The number group provided does not have a phone number in the group capable of the operation you are attempting + + + + + +- The message was attempted without a From number or Number Group + + + + + +- The 'From' number must belong to an active campaign + + + + + +- The E911 address ID provided is not valid + + + + + +- This number was purchased too recently to release + + + + + +- The validity period for the message was exceeded + + + + + +- The account balance is insufficient to send the message +- The account balance is insufficient for the operation you are attempting + + + + + +- The message was attempted but the destination handset is not reachable + + + + + +- The message was attempted but blocked by the destination carrier + + + + + +- The message was attempted but the destination handset is unknown + + + + + +- The message could not be routed to the destination handset + + + + + +- The message was flagged as a carrier violation +- The message was filtered due to disallowed content + + + + + +- The message failed due to an unknown upstream error + + + + + +- The message's validity period has expired at the carrier + + + + + +- The max price was exceeded by the cost of the message +- The max price was exceeded by the cost of the call + + + + + +- The US A2P 10DLC messaging rate limits were exceeded + + + + + +- The US A2P 10DLC T-Mobile Daily Message Limit was Reached + + + + + + +- The request resulted in a connection timeout + + + + + +- The websocket URL provided for the stream is invalid +- The websocket URL schema is not WSS +- The websocket URL has a trailing whitespace +- The websocket URL has an embedded whitespace + + + + + +- The SIP domain dialed is not a registered endpoint + + + + + +- The PFT Campaign daily message cap has been met +- The sole proprietor campaign daily message cap has been met + + + + + +- The redacted message body must be empty +- An attempt to redact the message by passing a different body was made + + + + + +- The URL returned an HTTP redirect +- The URL exceeded the max amount of HTTP redirects +- There was an internal failure while attempting to process the media + + + + + +- The PageToken provided is invalid or missing +- A PageToken must be included if your Page value is larger than 0 + + + + + +- The page size provided is invalid + + + + + +- The message could not be delivered to the carrier + + + + + +- The media could not be downloaded + + + + + +- The wildcard is invalid while searching for available numbers +- The format for the argument provided is invalid +- The supplied parameter is unsupported +- The supplied parameter can only be used in combination with InRegion +- The E911 address cannot be set on creation - update the record after it is created +- The specified capability could not be restricted on purchase + + + +## Warnings + + + +- The Conference noun cannot be mixed with Number nouns +- The Conference noun can only be used once inside a Dial verb + + + + + +- The Dial noun has an invalid nested element +- The only valid nested element for Dial is Number +- The Dial noun includes too many nouns +- The Refer noun has an invalid nested element +- No verbs can be nested within Refer, and Refer cannot be nested in any other verbs + + + + + +- The phone number in Dial is not formatted correctly. It must be E164 +- The phone number in Dial is missing +- You are attempting to Dial something that is not a phone number + + + + + +- There was an invalid Verb provided in the CXML executed by the waitUrl, holdUrl, or announceUrl +- The executed CXML contains Dial, Gather, Hangup, or Record - these are not allowed + + + + + +- The provided SIP URI is formatted incorrectly + + + + + +- The SIP URI provided for Dial -> SIP is missing +- The SIP URI provided for Dial -> SIP is not a public IP address +- The SIP URI provided for Dial -> SIP does not resolve + + + + + +- The URL provided for Play does not return audio +- The URL provided for Play has an invalid content type + + + + + +- The verb provided is not currently supported by the API version or your space + + + + + +- The Refer verb was used on a non SIP call leg + + + + + +- The queue name is too short +- The queue is missing in the attempt to Enqueue + + + + + +- The outbound phone call request was missing a 'To' number + + + + + +- The URL given to Play is not valid + + + + + +- The SIP URI provided is invalid +- The Refer verb contains an invalid SIP URI + + + + + +- The supplied codecs are unsupported or invalid + From ff8fe4b3033ba7117d18fc891be3d4ed50020eda Mon Sep 17 00:00:00 2001 From: manny-r31 Date: Thu, 23 Oct 2025 09:42:08 -0400 Subject: [PATCH 2/2] Readded guide links where applicable. --- .../compatibility-api/overview/error-codes.mdx | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/website/docs/main/rest/compatibility-api/overview/error-codes.mdx b/website/docs/main/rest/compatibility-api/overview/error-codes.mdx index bfb938708..667140b3f 100644 --- a/website/docs/main/rest/compatibility-api/overview/error-codes.mdx +++ b/website/docs/main/rest/compatibility-api/overview/error-codes.mdx @@ -473,12 +473,16 @@ Below is a list of all error codes as well as possible causes for the error code - The account balance is insufficient to send the message - The account balance is insufficient for the operation you are attempting + +[Troubleshooting Guide](/messaging/getting-started/how-to-troubleshoot-common-messaging-issues#30002) - The message was attempted but the destination handset is not reachable + +[Troubleshooting Guide](/messaging/getting-started/how-to-troubleshoot-common-messaging-issues#30003) @@ -491,12 +495,16 @@ Below is a list of all error codes as well as possible causes for the error code - The message was attempted but the destination handset is unknown + +[Troubleshooting Guide](/messaging/getting-started/how-to-troubleshoot-common-messaging-issues#30005) - The message could not be routed to the destination handset + +[Troubleshooting Guide](/messaging/getting-started/how-to-troubleshoot-common-messaging-issues#30006) @@ -504,12 +512,16 @@ Below is a list of all error codes as well as possible causes for the error code - The message was flagged as a carrier violation - The message was filtered due to disallowed content + +[Troubleshooting Guide](/messaging/getting-started/how-to-troubleshoot-common-messaging-issues#30007) - The message failed due to an unknown upstream error + +[Troubleshooting Guide](/messaging/getting-started/how-to-troubleshoot-common-messaging-issues#30008) @@ -529,6 +541,8 @@ Below is a list of all error codes as well as possible causes for the error code - The US A2P 10DLC messaging rate limits were exceeded + +[Troubleshooting Guide](/messaging/getting-started/how-to-troubleshoot-common-messaging-issues#30022)