What error codes may I see when sending messages over the MM4 interface?


Emma Bradley


When sending messages over the MM4 interface, you may see the error codes in the X-Internal-Status-Code field of the MM4_Forward.RES or the MM4_Delivery_Report.REQ. However, full visibility into the status of MMS messages isn't possible unless you request a delivery receipt (DLR) for messages. Most of these errors will only be available in the MM4_Delivery_Report.REQ when you request a delivery receipt.

In order to receive the MM4_Delivery_Report.REQ, you'll need to request a delivery receipt for the messages you're sending. You can request a DLR by enabling the X-Mms-Delivery-Report field in message type MM4_Forward.REQ. If a downstream carrier sends a MM4_Delivery_Report.REQ, Bandwidth will forward the message to the sender.

MM4 error codes

Error Code Error Description  Error Explanation Client/ Service Error Reported By
1 service-not-allowed This is a general error that the service you are attempting to use is not allowed; you may have inaccurate permissions, formatting or may not be enabled to use that service. Client Error Bandwidth Reported
201 temporary-rout-error-retries-exceeded Bandwidth service expired the message after attempts to deliver through retries failed. Service Error Bandwidth Reported
211 temporary-app-error-app-busy Bandwidth service application is temporarily busy, so it cannot receive messages at this time. Service Error Bandwidth Reported
220 temporary-store-error Message not received. Cannot save message to store. Service Error Bandwidth Reported
231 discarded-concatenation-timeout Bandwidth did not receive all parts of the message. Message cannot be sent. Service Error Bandwidth Reported
242 discarded-cannot-handle-udh-now Bandwidth service failed the message due to an error with the User Data Header (UDH). This could be because total parts in UDH does not match received before, duplicate message part (may be it is part of another message, but with same UDH ID) Service Error Bandwidth Reported
301 malformed-invalid-encoding The message contains invalid characters that are not supported. Bandwidth cannot re-encode message for destination. Client Error Bandwidth Reported
302 malformed-invalid-from-number The From number associated with the message is a number not routable to a carrier or valid in the industry (Ex: a 9 digit number). Client Error Bandwidth Reported
303 malformed-invalid-to-number The To number associated with the message is a number not routable to a carrier or valid in the industry (Ex: a 9 digit number). Client Error Bandwidth Reported
304 malformed-invalid-udh Invalid concatenation User Data Header (UDH), Bandwidth cannot process the message. Client Error Bandwidth Reported
305 malformed-invalid-udh Malformed User Data Header (UDH) length indicator: UDH length greater than message length, Bandwidth cannot process the message. Client Error Bandwidth Reported
306 malformed-invalid-dlr-flag Bandwidth cannot process the request for a delivery receipt (DLR) as the flag is not set properly. In case of ESME: registered delivery flag not in range [0, 1]. In case of SMSC: registered delivery flag not 0. Client Error Bandwidth Reported
350 malformed-for-destination Message passed validation on the receive stage, but failed on send. This is likely because the destination number (To) is an invalid number. Client Error Bandwidth Reported
352 malformed-too-large-for-destination The message size is too large for the destination carrier to support. Client Error Bandwidth Reported
401 rejected-loop-detected Message is looping within Bandwidth particularly when the source and destination are the same number. The destination or To number is mis-provisioned or there is a configuration with the message that is causing a situation where a message is being sent repeatedly between the same numbers. Client Error Bandwidth Reported
402 rejected-fail-with-code data_fail_with_code attribute set in source TN profile. Client Error Bandwidth Reported
403 rejected-forbidden-from-number Messaging on this From number is forbidden most commonly because the number does not belong to BW or the account. Other reasons include: the TN is not enabled in the Bandwidth Dashboard, the TN is disconnected, or it is an invalid number (i.e., 11111111111). Client Error Bandwidth Reported
404 rejected-forbidden-to-number Messaging on this To number is forbidden most commonly because  the number is not active, not enabled for messaging or is an invalid number (i.e., 11111111111). Client Error Bandwidth Reported
405 rejected-unallocated-from-number The From number is considered unallocated when the number does not exist in our database as an active number or the number is not enabled for messaging. Client Error Bandwidth Reported
406 rejected-unallocated-to-number The To number associated with this message, while a valid North American number, is not yet assigned to a carrier and the message cannot be sent downstream. Client Error Bandwidth Reported
407 rejected-account-not-defined-from-number Undefined source account ID. The From number associated with this message is not associated with this account, is an invalid number or not configured appropriately to send messages. Client Error Bandwidth Reported
408 rejected-account-not-defined-to-number Undefined destination account ID. The To (destination) number is not associated with an account, is an invalid number or not configured correctly to receive messages.  Client Error Bandwidth Reported
409 rejected-invalid-from-profile Bandwidth failed to create the destination and the destination profile is considered invalid. Typically  this is because the destination number does not support MMS. Client Error Bandwidth Reported
410 media-unavailable There was an error retrieving the media from the media web server. Check the media URL and try to access directly to see if the media can be fetched successfully. Client Error Bandwidth Reported
411 rejected-message-size-limit-exceeded The total size of MMS message media/attachments exceeded the max file size supported. Client Error Bandwidth Reported
412 media-content-invalid The media type is not a supported media content type. Client Error Bandwidth Reported
420 rejected-carrier-does-not-exist The upstream carrier associated with the message does not exist in Bandwidth’s configuration. Client Error Bandwidth Reported
421 rejected-forbidden-no-destination A DNS lookup issue has occurred or customer destination is not provisioned. Client Error  Bandwidth Reported 
431 rejected-forbidden-shortcode The message cannot be sent as the account associated with the message is not provisioned for Short code messaging. Client Error Bandwidth Reported
432 rejected-forbidden-country Bandwidth system indicates the account associated with the message is not enabled for messaging this zone, this country or this country is outside of messaging reach (specifically for MMS).  Client Error Bandwidth Reported
433 rejected-forbidden-tollfree Either the source or destination account is not enabled for toll free MMS. Client Error  Bandwidth Reported
435  forbidden-too-many-recipients The group message has too many recipients. When sending Group Messages, there's a maximum of 10 participants for an outbound group message. Client Error Bandwidth Reported
451  rejected-wrong-user-id The user ID is not valid or permitted to send messages on your account. Verify the user ID associated with your account and retry the message. Client Error Bandwidth Reported
452 rejected-wrong-application-id The application ID specified is not a valid Application ID or the application ID is not associated with the account. Client Error Bandwidth Reported
470 rejected-spam-detected This message has been filtered and blocked by Bandwidth for spam. Messages can be blocked for a variety of reasons, including but not limited to volumetric filtering, content blocking, SHAFT violation, etc.  Client Error Bandwidth Reported
492 reject-emergency Messaging to an emergency number is forbidden. Client Error Bandwidth Reported
500 message-send-failed

The destination carrier has reported a general service failure with sending the message.  

Service Error Bandwidth Reported
600 destination-carrier-queue-full Destination application cannot accept new messages at this time. This could result from network congestion, messaging queue full on the vendor side, or throttling error on the vendor side. Service Error Carrier Reported
620 destination-app-error The carrier is reporting a general error associated with their application processing the message. Service Error Carrier Reported
650 destination-failed Carrier Service is reporting a failure to send to destination. Service Error Carrier Reported
700 invalid-service-type Carrier rejected message for invalid service type. This usually means messaging (SMS or MMS) is not supported by the carrier or handset. Client Error Carrier Reported
720 invalid-destination-address Carrier Rejected as Invalid Destination Address. This could mean the number is not in the numbering plan (area code does not exist or the number is just invalid) or the number is not enabled for messaging (like a landline). Additionally, for toll-free messages to T-Mobile, this could also mean the user has opted to block all toll free and short code traffic. Client Error Carrier Reported
740 invalid-source-address Carrier is rejecting the message due to invalid source address - the number does not exist in the numbering plan. Other reasons for this error code is the source carrier is invalid/disabled, source not authorized or the number type is not supported.  Client Error Carrier Reported
750 destination-rejected-message The destination carrier has rejected the message but did not provide a specific reason. Specifically for AT&T traffic, this could be a prepaid user whose account is out of money, a subscriber that is provisioned to not receive this type of SMS or it was identified as Spam.  Client Error Carrier Reported
770 destination-spam-detected The Carrier is reporting this message as blocked for Spam. Some examples of common spam blocks: unwanted content, SHAFT violations (including specific keywords), or originating address has been flagged for repeated spam content.  Client Error Carrier Reported
775 destination-rejected-due-to-user-opt-out User has opted out of receiving messages from a particular sender. Remove the destination number from the subscriber list and cease communication with the destination. Client Error Carrier Reported
902 delivery-receipt-expired Bandwidth timed out waiting for the delivery receipt, this could be because the downstream provider did not send the requested delivery receipt or they sent after the system timed out at two hours.  Ambiguous Error Carrier Reported
999 unknown-error Bandwidth does not recognize the vendor's error response or does not have the vendor code mapped internally. Ambiguous Error Carrier Reported

Article is closed for comments.