HTTP Global SMS API
Delivery Receipts and Response Codes
FAQs
- Successful delivery: normally a few seconds to a few minutes, unless the first attempts to reach the handset fail.
- Unsuccessful delivery (after retries): normally up to three days. However, we will wait a maximum of 14 days for a delivery receipt from an operator.
If the mobile operator did not acknowledge the message request, nor responded in any further way, we will send you a delivery receipt after seven days identifying this issue. During this time we will have used a retry strategy if we don't believe the operator received the request.
If you message was split into multiple parts, then you will receive a delivery receipt for each part. Each part shares the same ticket ID. The delivery receipt will identify how many parts were used for the message and will identify which part is the receipt is for (totalSegments and segmentNumber).
However, for Get Message Status requests, we return the delivery status for each part in the same response. You will receive data about each part, including an individual receipt code and description, and you will also receive a summary receipt code and description. This code will help indicate the current status of the entire message:
Code 830, "Partial message delivery failure", means that at least one of the message parts has not been successfully delivered.
Code 831, "Awaiting complete message delivery status", means that the mobile operator has not returned a delivery receipt for one or more of the message parts. For example, you will get this code if one message part was successfully delivered but we do not have a receipt for the second part. However, if any message part fails delivery, then code 830 is returned.
Any other code means that the result for all parts of the message is the same. For example, if it is a "success" code of 0 or 4 then all parts were successfully delivered; if it is the same code to indicate a problem then all parts experienced the same problem.
In the SMS Activity Search available in Customer Center, a search by phone number returns all parts of a multipart message in the search results. OpenMarket Reports will also show each part of a multipart SMS as an individual SMS.
In both of these, the ticket ID you received is now also referred to as a Parent Ticket ID. You will also see a ticket ID for each individual part. However, you won't have received this additional ID from the API.
In the screenshot, you can see a five-part multipart message. Note that the ticket ID is in both the Parent Ticket ID column (for each part) and the Ticket ID column (once, to represent the entire message).
Response codes
Search this page for a specific code or by other text:
Status / Response Code |
Status Description |
Notes |
---|---|---|
0 |
Message sent |
OpenMarket successfully sent the message to the mobile operator. In some situations the mobile operator will not return any further update than this receipt (e.g. for a message sent using a US landline). If this is your final delivery receipt, treat this as a "successful" delivery. Retryable: n/a |
2 |
Message received |
OpenMarket has accepted and processed your message request but has yet to forward it to the mobile operator. You will only receive this receipt code in the response to a Get Message Status request. You are very unlikely to see this code unless you rapidly perform the request after submitting the message. This code is not returned for final delivery receipts. Retryable: n/a |
3 |
Message accepted by mobile operator. Awaiting receipt |
OpenMarket has sent the message to the mobile operator. We are still waiting for a response. You will only receive this receipt code in the response to a Get Message Status request. This code is not returned for final delivery receipts. Retryable: n/a |
4 |
Message delivered |
The mobile operator successfully delivered the message to the end user. Retryable: n/a |
321 | Invalid request version | Retryable: no |
322 | Invalid request protocol | Retryable: no |
323 | Invalid request type | Retryable: no |
339 | Carrier ID is not an integer. | Retryable: no |
341 |
Value of mobileOperatorID does not exist |
Your request specified a value for mobileOperatorId that is not one of the pre-defined IDs. For a list of the valid IDs, see Mobile Operator IDs. Retryable: no |
345 |
Mobile operator not found for the destination address |
OpenMarket performed an operator lookup for the end user's number and found that the number is not registered with any mobile operators. Note that the region in which we perform the lookup will depend on your messaging use cases — if you are only provisioned for US and Canadian messaging then we will only perform an operator lookup with the US and Canadian mobile operators. Therefore, requests to mobile numbers based in other destinations (like the UK) would come back with this error. Retryable: no |
349 | Unable to determine carrier ID from destination address. |
The carrier ID you provided is not associated with a carrier our system supports. Verify from MO SMS if possible. Please contact OpenMarket support for further information Retryable: no |
350 | Destination address contains non-numeric characters. |
Double-check the destination address to make sure it contains only numbers. Retryable: no |
351 |
Invalid destination address |
Mobile operators send us this delivery receipt for a variety of reasons. Unfortunately, these different error conditions are mixed between ones you could retry or not, based on the operator's own use of this code. If you are messaging anywhere outside of the US, we cannot refine the issue further, other than knowing that the message was sent using the right encoding to the correct mobile operator. OpenMarket has received more information from the US mobile operators. When messaging a US end user, the possible reasons can be one of:
In general, mobile operators do not want SMS senders to retry MT messages that have failed with error code 351. However, given the range of different possible root causes, we think it is reasonable to retry some of these messages. Here is our suggested behavior for US messaging:
Retryable: conditional |
352 | Invalid destination address country code | The MT source address country and destination address country do not match. For example, a message will fail with this status code when the MT source address is a US short code and the destination address is a Canadian number. |
355 |
Message text is too long |
OpenMarket did not forward the message to the mobile operator. This is because the message required multiple SMS parts, and your request did not specify to create a multipart or truncated message. This is set using mlc in your request. By default, mlc is set to reject messages; to change this behavior add mlc with either the option truncate or segment (creates a multipart message). Retryable: no |
368 | Invalid source address |
The mobile operator rejected the message with an invalid MT source address error. Contact your account manager to determine if your MT source address should be supported by the end user's mobile operator. Retryable: no |
375 |
Source address is blocked or is not provisioned |
Possible causes might be:
Talk to your OpenMarket account manager if you are unsure why you received this error. Retryable: no |
541 | The mobile operator accepted the message but delivery failed because the TPS was exceeded |
The message was blocked by AT&T because the TPS (transactions per second) limit on your messaging campaign has been exceeded. Retryable: Yes you can try re-sending the message, though delivery cannot be guaranteed. You may still encounter the TPS limit. |
542 | The mobile operator accepted the message but delivery failed because the daily bucket size has been exceeded |
The message was blocked by T-Mobile because the daily volume limit for your brand has been exceeded. You cannot resend the message until the next day. Retryable: no |
560 |
Mobile operator blocking the end user from this short code |
Retryable: no |
561 |
Content blocked by mobile operator for this end user |
The message was blocked by AT&T's spam filter. Retryable: no |
562 |
Short code not provisioned with mobile operator |
Contact your OpenMarket account manager if you believe that you are provisioned for the operator or if you want to begin provisioning. Retryable: no |
563 |
Short code expired with mobile operator |
Contact your OpenMarket account manager if you believe that you are provisioned for the operator or if you want to begin provisioning. Retryable: no |
564 |
Short code blocked by mobile operator |
The mobile operator rejected the message as the short code is currently blocked from sending messages across their network. Contact your OpenMarket account manager if you are unaware of why you have received this error. Retryable: no |
565 |
End users connected to this MVNO cannot receive short code messages |
The mobile operator rejected the message as the end user is connected to their network via a mobile virtual network operator (MVNO). This restriction is on short code messages. es. Retryable: no |
566 |
Destination address blocked by mobile operator |
The mobile operator is blocking the phone number from receiving messages from short codes. This is likely due to the end user's account being suspended or barred in some way. Retryable: no |
568 |
Destination address not provisioned for SMS |
Destination address not provisioned for SMS. Retryable: no |
569 |
Destination address suspended by mobile operator |
Destination address suspended by mobile operator. Retryable: no |
571 |
Program ID rejected by mobile operator |
This error applies to messages sent to US mobile operators. The error indicates the program ID in the message request is not provisioned with the mobile operator. Contact your account manager if you receive this error and believe that your program is provisioned or active with the mobile operator. Retryable: no |
572 |
Campaign is not provisioned for this mobile operator or is not active |
This error applies to messages sent to US mobile operators. OpenMarket has determined (before forwarding the message) that the campaign is not provisioned or is not currently active with the mobile operator. Contact your account manager if you receive this error and believe that your program is provisioned or active with the mobile operator. Retryable: no |
573 |
Short code blocked by end user |
The end user has asked their mobile operator to block any messages sent from your short code. Additional messages from the same short code must not be sent to the phone number unless the end user opts in again. Retryable: no |
574 |
New subscriptions for this short code are blocked by mobile operator |
Indicates that for a given short code, new subscribers are not allowed to receive or send messages. However, existing subscribers are still allowed to receive and send messages. This error is returned by Sprint US and Virgin Mobile USA. Contact your OpenMarket account manager if you are unaware of why you have received this error. Retryable: no |
577 |
Account not provisioned to use SMS demo short code |
Returned for US messaging only. You have attempted to use an OpenMarket short code that is reserved for demoing US messaging. Contact your account manager if you would like to try out US standard rate SMS using our demo short code. Retryable: no |
578 |
Exceeded the time limit for using SMS demo |
You can use demo OpenMarket SMS messaging for a limited time only. Contact your OpenMarket account manager to extend your trial. Retryable: no |
579 |
Destination address not in whitelist for SMS demo |
When demoing OpenMarket SMS messaging, you are limited to sending messages only to a whiltelist of mobile numbers you have told us you wish to message. The phone number you attempted to message is not on the whitelist. Contact OpenMarket Support to add the phone number to the whitelist. Retryable: no |
580 |
Exceeded the max number of demo requests |
You can only send a limited number of MT messages while demoing OpenMarket SMS messaging. Contact your OpenMarket account manager if you wish to extend this limit. Retryable: no |
581 |
End user out of prepay credit |
The end user does not have enough credit on their phone account to receive the message. You may retry every 24 hours for no more than seven days. Retryable: yes |
591 |
Exceeded the monthly limit on global MT messaging |
You have reached the agreed MT message limit on your account for global one-way and two-way messaging. Please contact your OpenMarket account manager if you want to discuss changing this limit. Retryable: no |
592 | Account not provisioned for global one- or two-way SMS |
The end user's number has a country code that is from a region of the world that you are not provisioned to reach. For example, if you exclusively message in the US or CA, you will not be provisioned for messaging end users who reside in other regions. If you'd like extend your messaging to reach end users globally, please contact your OpenMarket account manager. Retryable: no |
593 |
Cannot determine which message originator to use |
OpenMarket could not determine either the message originator to use or the interaction type for your message. This error occurs if you do not include one or more of: source address, ton, or interaction, and you have:
OpenMarket will not arbitrarily pick values to use. For more information see Automated Originator Selection and Message originators. Retryable: no |
597 |
Account has no provisioned address that can reach destination |
This error occurs if your message request does not include a source address (e.g. your message originator) and there is no pre-provisioned address suitable for messaging the end user. For example, this could occur if your normal messaging is to the UK only and you message another international number without having a default originator set for messaging to that region (or globally). Contact your OpenMarket account manager if you want to add a default originator for messaging to any new regions. Retryable: no |
598 |
Interaction not supported for message destination |
This error can occur if you set interaction to two-way. In some countries, OpenMarket supports one-way only. See our SMS Global Coverage Map. Retryable: no |
599 |
Values conflict for source address and interaction |
Your request specified an interaction and message originator that are incompatible. For example, you will receive this error if you specify "two-way" but your originator is an alphanumeric string, like "ACME123". Retryable: no |
600 |
Mobile operator <mobileOperatorID> does not support WAP Push |
This error can occur when sending a WAP Push to a US or Canadian end user. Not all mobile operators in this region support or allow WAP Push messages. We suggest resending the URL as plain text in an SMS message, as most smartphones will turn this into a hyperlink. Retryable: no |
601 |
Your account is not provisioned for global two-way SMS |
The message request had set interaction to two-way, however, your business account is not provisioned for global two-way messaging. The provisioning options are:
Note that you do not need to set a value for interaction for US and Canada messaging. Contact your OpenMarket account manager if you need global two-way messaging provisioned. Retryable: no |
603 | Content blocked by user opt-out (MO: STOP) |
This code can be returned in a delivery receipt for an MT originating from a North American, SMS-enabled toll-free number or an SMS-enabled landline number. Messaging can resume to the end user when he or she opts back in to your content. Retryable: no |
607 | This message was identified as spam and cannot be delivered |
The message was blocked by a spam filter and will not be delivered to the end user's handset. If you believe your message was falsely identified as spam, please submit a ticket to OpenMarket Support. Retryable: no |
628 | Temporary handset failure |
Communication to the end user failed, despite the end user's account being provisioned for SMS and the handset SMS-capable. This is typically a temporary failure -- for instance, the handset might be turned off or without coverage. Retryable: yes |
629 | Destination address unable to receive SMS |
Communication to the end user failed to due to either the handset not being SMS-capable or not provisioned for SMS. Retryable: no |
630 | Destination overload |
The destination mobile operator currently is unable to deliver SMS messages due to high traffic. Retryable: yes |
631 | Mobile operator network error |
The mobile operator network infrascture has returned an error. This might be at either the Mobile Switching Server (MSC), Short Message Service Center (SMSC), or Home Location Register (HLR). Retryable: yes |
632 | SMS rejected by mobile operator for attempted destination address |
The mobile operator is explicitly rejecting the request, possibly on the end user's behalf -- for example, the end user's handset might be set to Do Not Disturb (DND) or has been opted out of receiving service traffic. Retryable: yes |
633 | Message failed due to unknown mobile operator error |
The mobile operator returned a generic error for an unexpected failure in message delivery. Retryable: no |
810 |
Failed message delivery |
The mobile operator accepted the message, but has informed us that message delivery failed. They do not want retries of the same message. Unfortunately this message may be returned for a variety of reasons, which the mobile operator has decided not to distinguish between. Retryable: no |
811 |
Message expired before it reached handset |
OpenMarket and/or the mobile operator attempted to deliver the message to the end user for the duration of the MT validity period. However, the message never reached the end user's handset. You can set a validity period in the MT message request. If you did not supply a validity period in the MT, MT delivery is generally retried for up to three days before expiring the MT. Retryable: yes |
815 |
Message submitted to but not acknowledged by mobile operator |
When OpenMarket sends a message to a mobile operator, we expect to receive an asynchronous reply confirming that the message was received. If we don't receive a response (and after using our retry strategy) then we will return this error to you. It is possible that the end user may have received one or more of the same message (or not received the message at all). Retryable: yes |
830 |
Partial message delivery failure |
This means that at least one part of a multipart message has not been successfully delivered. You can receive this receipt code in the response to a Get Message Status request. However, this code is not returned for final delivery receipts. Retryable: n/a |
831 |
Awaiting complete message delivery status |
This means that we have not received delivery receipt data for at least one part of a multipart message. For example, you will get this code if one message part has been successfully delivered but we do not have a receipt for the second message part. However, if any message part has failed delivery, then code 830 is returned. You can receive this receipt code in the response to a Get Message Status request. However, this code is not returned for final delivery receipts. Retryable: n/a |
1010 |
Temporary system error |
OpenMarket was unable to finish processing the request; therefore, your message was not sent. You can retry your request in intervals of 10 seconds or more. If you continue to receive this error, contact OpenMarket Support. Retryable: yes |
1020 |
Temporary mobile operator system error |
The mobile operator is experiencing an outage or system error that should resolve itself shortly. If retries fail beyond the recommended retry period please contact OpenMarket Support for assistance troubleshooting. Retryable: yes |
1030 |
Non-retryable mobile operator system error |
The mobile operator is experiencing an outage or system error during which they do not want messages retried. Check the system status as reported by OpenMarket via email and on Customer Center, and use a slow retry strategy to test for connectivity; e.g. one request attempt every 20 minutes. Retryable: no |
3041 |
US standard rate message blocked by the OpenMarket deactivated numbers firewall |
The phone number is on a list of deactivated numbers, originally provided by the mobile operator. If your request included mobileOperatorId, then try an operator lookup to see whether the number was ported. If your request didn't include mobileOperatorId, then we will already have performed an operator lookup. In this case, the number was not ported to a new operator, and is completely deactivated. It is important that you don't send further messages to the number. For more information see Handling Deactivated Phone Numbers. Retryable: no |