Response and Delivery Receipt Codes for SMS Version 3 API

Note: These response codes are for our SMS version 3 HTTP API. If you're new to OpenMarket, then integrate with our Global SMS (version 4) operations.
Customers currently integrated using v3 may continue to use it, although we encourage customers to migrate to v4 in order to take advantage of new features.

You can treat code 0 and 4 as meaning that the message was successfully delivered.

Codes 1, 2, and 3 are returned only when the request is still being processed in some way.

All other codes returned indicate an issue with either the request format, your account settings, or with reaching the end user in some way. The retryable codes are:

  • 351
  • 581
  • 811
  • 815
  • 1010
  • 1020

Any other returned code indicates that you may need to investigate what occurred before you can attempt sending the message again.

Code

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

1

Processing request

The message is still being processed by OpenMarket.

Retryable: n/a

2

Message accepted

OpenMarket has accepted and processed your message request but has yet to forward it to the mobile operator.

Retryable: n/a

3

Message buffered with carrier and waiting for a response

OpenMarket has sent the message to the mobile operator. We are still waiting for a response.

Retryable: n/a

4

Message delivered

The mobile operator successfully delivered the message to the end user.

Retryable: n/a

301

Only one top level request element is permitted

Your message request was malformed. You will need to correct this before attempting another request.

Retryable: no

303

The required version attribute of the request element was not found in the request

Your message request was malformed. You will need to correct this before attempting another request.

Retryable: no

304

The required protocol attribute of the request element was not found in the request

Your message request was malformed. You will need to correct this before attempting another request.

Retryable: no

306

The XML POST parameter cannot be empty

Your message request was malformed. You will need to correct this before attempting another request.

Retryable: no

307

The request was an ill-formed XML document

Your message request was malformed. Common causes are: setting a url_encoded content-type, missing parameters, or incorrect syntax in the XML.

You will need to correct this before attempting another request.

Retryable: no

321

Invalid request version Retry Prohibited SMS Messaging No

Your message request was malformed. You will need to correct this before attempting another request.

Retryable: no

322

Invalid request protocol

Your message request was malformed. You will need to correct this before attempting another request.

Retryable: no

323

Invalid request type

Your message request was malformed. You will need to correct this before attempting another request.

Retryable: no

337 Invalid carrier ID value

The OpenMarket carrier ID is not an active carrier.

Retryable: no

339

Carrier ID is not an integer

In your request, the carrier ID sent was not an integer, or the carrier ID attribute was submitted with a null value.

You will need to correct this before attempting another request.

Retryable: no

341

The carrier ID does not exist

The ID is not a known OpenMarket carrier ID.

Retryable: no

345

Unable to determine carrier ID from destination address

Number not associated with a carrier our system supports. Verify from MO SMS if possible. Please contact OpenMarket support for further information.

Retryable: no

349

Destination address contains non-numeric characters

The destination address must be a valid mobile number. Do not include a leading "+" character.

Retryable: no

350

A destination address is required

Check the destination address against the list of deactivated numbers in Customer Center; if the number is listed you cannot resubmit the billing to the destination address unless you receive an opt-in from a wireless subscriber.

Retryable: no

351

Transaction failed: Invalid destination address value

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:

  • Any operator: The mobile number is not on the mobile operator's network.
  • Any operator: The mobile number has been deactivated. Check the Deact reports on Customer Center.
  • Any operator: The mobile number has been deactivated. Check the Deact reports on Customer Center.
  • T-Mobile and MetroPCS: The phone number belongs to a prepaid user who does not have enough credit to receive an SMS.
  • T-Mobile only: The end user is not provisioned to receive SMS from all short codes (or from specific short codes).
  • T-Mobile only: The end user is on a MVNO connected via T-Mobile. T-Mobile does not deliver SMS messages from short codes to end users on MVNOs.
  • AT&T US: There are several possible causes for the error:
    • The phone number belongs to a prepaid user who does not have enough credit to receive an SMS.
    • The phone number is not provisioned for SMS.
    • The phone number could be blocked due to a spam complaint.

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:

  • Perform a number preview request to confirm that the number is on the mobile operator's network.
  • Check the Deact reports to ensure the number is still live
  • For T-Mobile specifically, you could retry the message using a US VMN or other number
  • If desired, retry the message using a slow retry method; for example, retrying once every day for up to 7 days

Retryable: conditional

352

Invalid destination address country code

This error occurs in MTs when the country calling code of the destination address does not match the country provisioned for the source address. This error also occurs if a standard rate (charge type 0) MT is submitted to a destination address outside of the US and Canada.

Retryable: no

353

Message text or data is required

You have not sent us any text (or data) content for the SMS message. You cannot send a blank message.

Retryable: no

354

Message text is not long enough

You have not sent us any text content for the SMS message. You cannot send a blank message.

Retryable: no

355

Message text is too long

If the mlc option was submitted with a value of 0 or the default value of 0 is applied, the submitted message will be rejected if the message text or data length is greater than the maximum single segment message length allowed: generally 160 characters for 7BIT datacoding and 70 characters for the UCS2 datacoding.

Retryable: no

358

Message from is too long

Message requires a source address, verify one is provided, and is correct.

Retryable: no

365

Strict international addressing is enforced, please use a country code + national number

Ensure you address are set with the proper source types, most likely use TON = 1 and begin the number with the destination country code.

Retryable: no

366

Invalid message length control option

There are only 3 valid values for this option: 0, 1 and 2.

Retryable: no

367

Invalid source TON value

Source ton most likely needs to be 3 when using short codes, 1 when using long codes

Retryable: no

368

Invalid source address value

Message requires a source address, verify one is provided, and is correct for the locale of the destination address.

Retryable: no

369

Account not permitted to use an alphanumeric source address

You have specified an alphanumeric string as your sender (source) address, rather than a short code or other number. To use an alphanumeric string, you must be provisioned in our systems first.

If you did not intend to send a string, check that you have not included any additional characters in the address.

Retryable: no

370

Account not permitted to use a short code source address

This most likely indicates an account provisioning issue. Check with OpenMarket.

Retryable: no

373

Invalid destination TON value

Ensure that your Destination TON value equals 1 or 0 (international or unknown) for phone numbers.

Retryable: no

374

Preview lookup request failed

Preview may have timed out, reattempt, contact support if persistent.

Retryable: no

375

Source address denied

Account not configured to send from this short code, ensure correct account or contact support.

Retryable: no

376

Account not permitted to use premium billing options

Premium SMS is no longer supported in SMS version 3.

Retryable: no

377

Invalid SMS charge type

Charge type must be either 0 for US and Canada standard rate SMS, or 20 for international SMS.

Retryable: no

378

Invalid premium billing charge amount

Account not configured to send charge amount, possible currency issue.

Retryable: no

379

Invalid user data header

We could not parse your user data header.

Retryable: no

380

Invalid data coding scheme

The value of the datacoding attribute submitted in the message is not a supported value.

Retryable: no

381

Invalid characters used with selected data coding scheme

Retryable: no

382

Invalid source or destination port

Retryable: no

383

Message data and text attributes cannot be used at same time

If sending data, no text can be sent.

Retryable: no

384

Invalid message data

Retryable: no

388

Binary messaging is not supported for this carrier

The mobile operator does not support WAP push or similar data transfer

Retryable: no

397

WAP Pushes require the optional URL parameter to be included

To send a WAP Push, you must include the url parameter in your request.

Retryable: no

398

WAP Pushes not supported for this type of carrier

Retryable: no

420

Invalid account ID or account password

Your account ID and password were not recognized. You should check that both are correct before resending the request.

Retryable: no

431

Invalid account ID Account ID incorrect, or formatted incorrectly

Retryable: no

432

Account access permanently blocked

Your account has been blocked, please consult your OpenMarket account manager for more information.

Retryable: no

433

Account access denied

Retryable: no

451

Account mobile originated deliver profile incorrectly setup

Contact OpenMarket Support if you see this error in your OpenMarket SMS reports.

Retryable: no

540

Invalid Request - <description>

Your request was malformed in some way; for example, a required element or attribute was missing or misspelled. The response message will include a description that varies depending on the issue.

Retryable: no

560

Message recipient not authorized by carrier to receive the message

Retryable: no

561

Content blocked by carrier

Retryable: no

562

Short code not active

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

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

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

Reseller address blocked by carrier

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.

Retryable: no

566

Destination address blocked by carrier

Retryable: no

568

Destination address not provisioned for SMS

Destination address not provisioned for SMS.

Retryable: no

569

Destination address suspended by carrier

Destination address suspended by mobile operator.

Retryable: no

570

Invalid charge amount: charge amount not allowed for charge type

You cannot include a charge amount in your request for charge type 20.

Retryable: no

571

Campaign rejected by carrier

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: Retry only once the campaign has been corrected with the mobile operator.

572

Campaign information is not provisioned for this carrier or is not active.

This error applies to messages sent to US mobile operators. OpenMarket has determined (before forwarding the message) that the program ID in the message request 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: Retry only if and when the campaign or program ID has been corrected.

573

Short code blocked by subscriber

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

Subscribers are not allowed to receive or send messages on this short code.

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

575

Account not permitted to submit preview requests

Retryable: no

577

US SMS Demo Product required for this short code

Contact your account manager for a demo of US standard rate SMS.

Retryable: no

578

Demo product expired

The SMS demo you are using for US or International SMS has expired. Contact your account manager.

Retryable: no

579

Destination address not provisioned for this demo product

Contact OpenMarket Support to provision the phone number to use with the demo product.

Retryable: no

580

Demo product transaction limit exceeded

If you are using an SMS demo, you have reached the limit of MTs you can send with the demo. If you are using the Preview Lookup demo, you have reached the limit of Preview Lookups available for the demo. Contact your account manager.

Retryable: no

581

Prepaid subscriber out of credits

You may retry every 24 hours for no more than seven days.

Retryable: yes

590

Invalid purpose for India SMS

You must specify a purpose when sending to India.

Retryable: no

591

Monthly MT limit exceeded

You may contact your account manager if you would like to increase your monthly international MT limit.

Retryable: no

592

Your account is not provisioned for international SMS

You may contact your account manager if you would like to sign up for international SMS.

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 if the end user opts back in to your program.

Retryable: no

607 This message was identified as spam and cannot be delivered.

Content was blocked by the mobile operator due to that mobile operator's spam filter. The message will not arrive on the end-user's handset.

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

711

Ticket ID does not exist.

Retryable: no

810

Failed message delivery

The mobile operator failed to get the text message to the end user's handset. This code is used when the mobile operator does not want retry attempts for the message.

Retryable: no

811

Message Delivery Error - Message expired

OpenMarket and the mobile operator attempted to deliver the message but could not reach the handset. If you set a validity period in the message request, then the message was tried for the duration of that period. If you did not set a validity period, then the mobile operator has used their own expiry time (normally around three days).

Unlike code 810, you can retry the message.

Retryable: yes

815

Message Delivery Error - Message submitted to but not acknowledged by carrier

You can retry this message; however, it is possible that the end user will receive the message multiple times.

Retryable: yes

1000

System error: General error occurred while processing request

Retryable: no

1010

Temporary internal system error

Retryable: yes

1020

Temporary external system error

If retries fail beyond the recommended retry period please contact OpenMarket Support for assistance troubleshooting.

All Carriers: Retry every 24 hours for a period of seven days.

T-Mobile USA: A 1020 response for for this carrier may either indicate a system error within T-Mobile USA or the following for the phone number:

Content Blocking/Blacklisting/Family Allowance is enabled. It is important to note the only way family allowance; content blocking or blacklisting occurs is if the mobile subscriber called into T-Mobile customer care and specifically requested blocking of short code services.

T-Mobile USA does not provide sufficient detail for OpenMarket to distinguish between the two potential causes for the 1020 response code.

Retryable: yes

1030

External system error

Retryable: no

3041

US standard rate message blocked by the OpenMarket deactivated numbers firewall

Occurs when a US standard rate SMS message is sent to a deactivated number.

Retryable: no