Skip to main content

Errors

The Bandwidth Messaging API will report delivery outbound errors via Webhooks and message creation errors via the HTTP status codes.

HTTP Status Codes#

Bandwidth will respond with HTTP errors code when the message creation request fails. Any 4xx or 5xx HTTP response code will not be billed nor will the message be sent.

Bandwidth will return a HTTP-400 Error when the request is malformed or invalid. See the message of the error for tips before trying again.

Status: 400 Bad Request
Content-Type: application/json; charset=utf-8
{
"type": "request-validation",
"description": "Your request could not be accepted"
}

Messaging Errors#

The Bandwidth V2 messaging API presents errors to your Webhook URL using the message-failed type in the payload body along with an errorCode and description.

Error Code Schema#

Bandwidth’s error code schema for messaging V2 is comprised of a 4 digit code. As shown in the table below, the most significant digit indicates whether the error is client (customer) or server in nature while the second most significant indicates whether the error was reported by Bandwidth or the downstream carrier. The last 2 are Bandwidth specific codes or bandwidth normalization of carrier specific codes.

Client / Server

Digit

Bandwidth / carrier

Digit

X

X

4

Client error

1

Bandwidth Rejected

Bandwidth Specific

3

4

7

Carrier Rejected

Carrier Normalized

5

Server Error

1

Bandwidth Server Error

Bandwidth Specific

2

5

6

Carrier Reported Service Failure

Carrier Normalized

9

Ambiguous Error

The error is related to downstream failures, but the specific reason for failure is unclear.

Bandwidth Detected Client Errors#

A 4xx code indicates that Bandwidth or the downstream carrier has identified some element of the message request unacceptable. Repeating the request will produce the same result.

CodeDescriptionFriendly DescriptionExplanation Of ErrorBillable
4001service-not-allowedMessage was rejected for reasons other than those covered by other 4xxx codesThis 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 enable to use that service.NO
4301malformed-invalid-encodingMalformed message encodingThe message contains invalid characters that are not supported. Bandwidth cannot re-encode message for destination.NO
4302malformed-invalid-from-numberMalformed From numberThe From number associated with the message is a number not routable to a carrier or valid in the industry (Ex: a 9 digit number).NO
4303malformed-invalid-to-numberMalformed To NumberThe To number associated with the message is a number not routable to a carrier or valid in the industry (Ex: a 9 digit number).NO
4350malformed-for-destinationMalformed message encodingMessage passed validation on receive stage, but failed on send. This is likely because the destination number (To) is an invalid number.NO
4360message-not-sent-expiration-date-passedMessage expiredMessage was not sent because the specified expiration date passed before the message was able to sendNO
4401rejected-routing-errorBW is unable to route the messageMessage is unable to be routed 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.NO
4403rejected-forbidden-from-numberMessaging forbidden on From numberMessaging 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 account associated with this number is not enabled for this type of messaging, the TN is disconnected, or it is an invalid number (i.e., 11111111111).NO
4404rejected-forbidden-to-numberMessaging forbidden on To numberMessaging on this To number is forbidden. This could be the number is not active, not enabled for messaging or is an invalid number (i.e. 11111111111)NO
4405rejected-unallocated-from-numberUnallocated from numberThe From telephone number is considered unallocated when the number does not exist in our database as an active number. This number is either not enabled for messaging at the industry level, or the number is not yet released in the industryNO
4406rejected-unallocated-to-numberUnallocated to numberThe 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.NO
4407rejected-account-not-defined-from-numberFrom Number is associated with accountUndefined 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.NO
4408rejected-account-not-defined-to-numberTo Number not associated with accountUndefined destination account id. The To (destination) number is not associated with an account, is an invalid number or not configured correctly to receive messages.NO
4409rejected-invalid-from-profileInvalid destination profileBandwidth failed to create destination. The destination profile is considered invalid, most often this is because the destination number does not support MMS.NO
4410media-unavailableCould not download mediaThere 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.NO
4411rejected-message-size-limit-exceededCombined size of media too largeThe total size of MMS message media/attachments exceeded the max file size supportedNO
4412media-content-invalidFailed to parse Content-Type for mediaThe media content type is not a supported media content type.NO
4420rejected-carrier-does-not-existNo Route to Destination CarrierThe upstream carrier associated with the message does not exist in Bandwidth configurationNO
4421rejected-forbidden-no-destinationNo Route to Destination CarrierThe message cannot be sent downstream as the account associated with the message does not have permission to send to this destination. You may not be provisioned to send to this destination.NO
4431rejected-forbidden-shortcodeMessaging on shortcode forbiddenThe message cannot be sent as the account associated with the message is not provisioned for Short code messagingNO
4432rejected-forbidden-countryMessaging to country forbiddenBandwidth 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).NO
4433rejected-forbidden-tollfreeMessaging on Toll Free Number ForbiddenThe account associated with this message is not enabled for toll free messagingNO
4434rejected-forbidden-tollfree-for-recipientMessaging to Toll Free Number ForbiddenMessaging to this toll free number is not allowed. Number is likely not enabled for messaging or not active.NO
4435forbidden-too-many-recipientsToo Many RecipientsThe group message has too many recipients. When sending Group Messages, there's a maximum of 10 participants in a Group.NO
4451rejected-wrong-user-idInvalid User IdThe user id is not a valid id. Verify the user ID and retry the messageNO
4452rejected-wrong-application-idInvalid Application IDThe Application ID specified is not a valid Application Id, or the Application ID is not associated with the accountNO
4470rejected-spam-detectedRejected as SPAM (future)This message has been filtered and blocked by a downstream carrier for spam. Messages can be blocked for a variety of reason, including but not limited to volumetric filtering, content blocking, SHAFT violation, A2PYES
4481rejected-from-number-in-blacklistFrom Number in black listThe From number has been flagged by Bandwidth as prohibited from sending messages. This is typically because Bandwidth or a downstream carriers has several violations; reports of spam, P2P violations, associated with this number.NO
4482rejected-to-number-in-blacklistTo Number in black listThe number you are attempting to send to is blocked from receiving messages.NO
4492reject-emergencyMessage to emergency number forbiddenMessaging to an emergency number is forbiddenNO
4493rejected-unauthorizedUnauthorizedBandwidth service indicates the sender is not authorized to send messages from the account.NO

Carrier Reported Client Errors#

CodeDescriptionFriendly DescriptionExplanation Of ErrorBillable
4700invalid-service-typeCarrier Rejected as Invalid Service TypeCarrier rejected message for invalid service type. This usually means messaging (SMS or MMS) is not supported by the carrier or handset.YES
4701destination-service-unavailableDestination is not reachable and SMS service is not available.Carrier service is reporting the destination is not reachable or the SMS service is not available. YES
4702destination-subscriber-unavailableDestination subscriber is unavailable.This error indicates the subscriber is unavailable. There are several reasons for this; the subscriber has turned off handset, the destination is unreachable or barred, the GSM subscriber is busy for outbound SMS, SIM card is full, voicemail is full, or cannot reach the destination handset and has stored the message for retry in its « Store & Forward » function. YES
4711rejected-message-size-limit-exceededMedia size too largeDownstream vendor cannot retrieve the media as the MMS attachment is too largeYES
4712media-invalidInvalid mediaThe end user’s handset cannot download the MMS or the media is not formatted in a way the end user can open on their handset.YES
4720invalid-destination-addressCarrier Rejected as Invalid Destination AddressCarrier 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 TMobile, this could also mean the user has opted to block all toll free and short code trafficYES
4721destination-tn-deactivatedTN on deactivation listThe phone number you are attempting to send to is on the deactivation list. It is not associated with a carrier to be able to receive messages or is inactive.YES
4730no-route-to-destination-carrierNo route to destination carrier or no roaming route exists.Carrier is reporting there is no route available for message. This could be because no routing exists to destination, no roaming route is available, the destination handset is roaming on a network that cannot be reached, no SS7 route, or routing was deniedYES
4740invalid-source-address-addressCarrier Rejected as Invalid Source AddressCarrier 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 or disabled or source not authorized or the number type is not supported.YES
4750destination-rejected-messageCarrier Rejected MessageThe destination carrier has rejected the message but provided no specific reason. 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 SpamYES
4751destination-rejected-message-size-invalidMessage is too long or message length is invalid for the carrier.Carrier has rejected for message length is invalid or too long.YES
4752destination-rejected-malformedMessage is malformed for the carrier.Carrier is rejecting the message malformed; this could be because of a blank message, unacceptable data value, the receiving SMSC or SME does not accept messages with more than 160 characters, syntax error, content is invalid, message ID is invalid, invalid parameter length, expected TLV missing, invalid TLV value, invalid data coding scheme, invalid number of destinations, error in the optional part of the PDU body, TLV not allowed, or XML validation error.YES
4770destination-spam-detectedCarrier Rejected as SPAMThe Carrier is reporting this message as blocked for SPAM. Spam blocks could be a result of content, SHAFT violations (including specific keywords), originating address has been flagged for repeated spam contentYES
4775destination-rejected-due-to-user-opt-outCarrier Rejected due to user opt outUser has opted out of receiving messages from a particular sender. Remove the destination TN from subscriber list and cease communication with the destination.YES
4780p2p-volume-violationCarrier rejected due to P2P volumetric violationCarrier rejected due to P2P volumetric violation. You are sending at a higher rate (mps) than is allowed for P2P traffic. Please contact BW support to review your account settings and ensure you are utilizing the appropriate A2P channels for high volume trafficYES
4790destination-rejected-sc-not-allowedCarrier Rejected Due to Short Code RestrictionCarrier Rejected Due to Short Code Restriction. Destination address blocked by mobile operator, destination cannot receive short code messages, or the mobile operator blocked the destination from receiving messages from this short code for some other reason.YES
4791destination-rejected-campaign-not-allowedCarrier Rejected Short Code Campaign Not AllowedCarrier Rejected SC Campaign Not Allowed or blocked by the mobile operatorYES
4792destination-rejected-sc-not-provisionedCarrier Rejected Short Code Not ProvisionedShort Code not provisioned on mobile operator's network.YES
4793destination-rejected-sc-expiredCarrier Rejected Short Code ExpiredShort Code expired with the mobile operatorYES

Bandwidth Service Failures#

A 5xx code indicates that either Bandwidth or the downstream carrier has reported a service failure. For Bandwidth failures, the customer can retry the request and expect a different result. For carrier errors a retry may also yield a different result however the customer should limit to a single retry attempt as the error encoding schema and strategy varies greatly by carrier and while Bandwidth endeavors to normalize carrier codes into predictable values there can be exceptions.

CodeDescriptionFriendly DescriptionExplanation Of ErrorBillable
5100temporary-app-errorApplication ErrorAn application within the Bandwidth service is experiencing a temporary error that is preventing the message from being processed.NO
5101temporary-app-shutdownApplication ErrorApp going down. Message not received. Sender should send this messages later or to other host.NO
5106impossible-to-routeImpossible to route / Attempt to deliver through retries has failed.Impossible to route / Attempt to deliver through retries has failed.NO
5111temporary-app-connection-closedApplication ErrorReceived messaged for connection which is already removed.NO
5201temporary-rout-error-retries-exceededApplication ErrorBandwidth service expired the message after attempts to deliver through retries failed.NO
5211temporary-app-error-app-busyApplication ErrorBandwidth service application is temporarily busy so it cannot receive messages at this timeNO
5220temporary-store-errorApplication ErrorMessage not received. Cannot save message to store.NO
5231discarded-concatenation-timeoutApplication ErrorBandwidth did not receive all parts of message. Message can not be sent.NO
5500message-send-failedGeneral Message Send FailureThe destination carrier has reported a general service failure with sending the message.NO
5501message-send-failedGeneral Message Send FailureThe message is unable to send as no destination is available.NO
5999unknown-errorUnknown error from BandwidthUnknown error generated by Bandwidth when Bandwidth core reports an unknown errorNO

Carrier Reported Service Failures#

CodeDescriptionFriendly DescriptionExplanation Of ErrorBillable
5600destination-carrier-queue-fullCarrier Service UnavailableCarrier Service Unavailable. This could result from network congestion, messaging queue full on the vendor side, throttling error on the vendor side.YES
5610submit sm-or-submit multi-failedCarrier Service FailureThe downstream carrier application is experiencing an error. submitting the message has failed or cancelling message has failedYES
5620destination-app-errorCarrier Application ErrorThe carrier is reporting a general error associated with their application processing the message.YES
5630message-not-acknowleCarrier Application ErrorNACK - no response or acknowledgement received from the carrierYES
5650destination-failedCarrier Service FailureCarrier Service is reporting a failure to send to destination (mobile operator or handset).YES

Carrier Errors with Ambiguous Cause#

CodeDescriptionFriendly DescriptionExplanation Of ErrorBillable
9902delivery-receipt-expiredTimed out waiting for delivery receipt. The reason a delivery receipt was not received is not known.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.YES
9999unknown-errorUnknown error from downstream. Carrier reported a failure code that is unknown to Bandwidth.Bandwidth does not recognize the vendor's error response or does not have the vendor code mapped internallyYES