# Status Codes & Errors

View the description of possible status and error codes: 

* [Message Status Table](#message-status-table)
* [Errors Table](#errors-table)

## Message Status Table

### Successful flow of messages

<table><thead><tr><th width="101">Status Code</th><th width="239">Callbacks; Query Message Response (description presented to clients)</th><th>Short Description</th><th>Details</th></tr></thead><tbody><tr><td>1</td><td>UNKNOWN</td><td>Message not found</td><td>The specified message was not found in the account. Please check the account details and message ID to ensure these are correct.</td></tr><tr><td>2</td><td>QUEUED</td><td>Message is queued</td><td>The message has been queued for delivery. This is a temporary status – please check again in a few hours.</td></tr><tr><td>3</td><td>SCHEDULED</td><td>Message scheduled for later delivery</td><td>The message is scheduled for later delivery. Review the message in a few hours to check on delivery.</td></tr><tr><td>4</td><td>SENT_TO_SUPPLIER</td><td>Sent to supplier</td><td>This message has been submitted to an external supplier. <em>(For WhatsApp messages, this means Meta.)</em></td></tr><tr><td>5</td><td>DEVICE_ACK</td><td>Device acknowledged delivery</td><td>Two gray checkmarks on WhatsApp. The message was delivered successfully to the customer’s device. <em>(WhatsApp-specific behavior)</em></td></tr><tr><td>6</td><td>READ</td><td>Read receipt</td><td>Two blue checkmarks on WhatsApp. The customer has read or opened the message. <em>(WhatsApp-specific behavior)</em></td></tr></tbody></table>

####

### **Generic errors (shared by all channels)**

<table><thead><tr><th width="89">Status Code</th><th width="243">Callbacks; Query Message Response (description presented to clients)</th><th>Short Description</th><th>Details</th></tr></thead><tbody><tr><td>20</td><td>EXPIRED</td><td>Message has expired.</td><td>Validity period or internal validity period-related.</td></tr><tr><td>21</td><td>STOPPED_BY_USER</td><td>Message stopped by the user.</td><td></td></tr><tr><td>22</td><td>STOPPED_BY</td><td>Message stopped by admin.</td><td></td></tr><tr><td>23</td><td>DELIVERY_FAILURE</td><td>Error delivering message.</td><td>Generic upstream supplier returned a permanent error. Could also be an internal error.</td></tr><tr><td>24</td><td>EMULATED</td><td>Emulated.</td><td>Used for sandbox messaging when the number being sent to has not been added as a test phone.</td></tr><tr><td>25</td><td>INSUFFICIENT_ACCOUNT_BALANCE</td><td>Insufficient account balance.</td><td>Review your account balance and ensure you have enough funds available.</td></tr><tr><td>26</td><td>VOLUME_LIMIT</td><td>Volume limit exceeded</td><td></td></tr><tr><td>27</td><td>VOLUME_LIMIT_DAILY</td><td>Daily volume limit exceeded.</td><td>Applies to the sandbox environment.</td></tr><tr><td>28</td><td>VOLUME_LIMIT_MONTHLY</td><td>Monthly volume limit exceeded.</td><td>Applies to the sandbox environment.</td></tr><tr><td>29</td><td>RECIPIENT_DOES_NOT_EXIST</td><td>Recipient does not exist on channel.</td><td></td></tr><tr><td>30 </td><td>STOP_MARKETING_MESSAGES</td><td>Recipient does not want to receive marketing messages.</td><td>A message did not deliver because the end user previously indicated that they do not want marketing messages from your business. It is possible that the user will allow marketing messages again in future.</td></tr><tr><td>31</td><td>EXCESSIVE_MESSAGES_SENT_TO_RECIPIENT</td><td>Your business sent too many messages to the recipient in a short period.</td><td>Occurs when too many messages are sent from one sender to the same recipient in a short period. This issue sometimes happens when a campaign includes the same end user’s number multiple times in the database.</td></tr></tbody></table>

####

### Encryption-related

| Status Code | Callbacks; Query Message Response (description presented to clients) | Short Description            | Details                                                                                                                                                                                                                |
| ----------- | -------------------------------------------------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 60          | ENCRYPTION\_ACCESS\_DENIED                                           | Security access denied.      | Credentials are invalid or have expired.                                                                                                                                                                               |
| 61          | ENCRYPTION\_CONTENT\_ERROR                                           | Content decryption failed.   |                                                                                                                                                                                                                        |
| 62          | ENCRYPTION\_VALIDATION\_ERROR                                        | Encryption validation error. | <p></p><p>Possible causes:</p><ul><li>The media file was expected to have an <em>encryptionKey</em> field, but it was not present.</li><li>Mixing encrypted messages with non-encrypted media or vice versa.</li></ul> |

### Anonymous messaging status

| Status code | Callbacks; Query Message Response (description presented to clients) | Short description                                                  | Details                                                                                                                                                            |
| ----------- | -------------------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 70          | ANONYMOUS\_USER\_ID\_INVALID                                         | Anonymous user ID not found.                                       | The anonymous user ID specified by the customer was not found.                                                                                                     |
| 71          | ANONYMOUS\_USER\_ID\_ERROR                                           | Could not determine message receiver from valid anonymous user ID. | Could not determine message receiver from valid anonymous user ID – this is usually when an error occurred when trying to decrypt the internally decrypted number. |
|             |                                                                      |                                                                    |                                                                                                                                                                    |

### Media-related

<table><thead><tr><th width="83">Status Code</th><th>Callbacks; Query Message Response (description presented to clients)</th><th>Short Description</th><th>Details</th></tr></thead><tbody><tr><td>80</td><td>MEDIA_NOT_FOUND</td><td>Media not found.</td><td>Ensure that media is present in your upload environment and that it adheres to <a href="https://docs.clickatell.com/channels/one-api/supported-content-types/">supported media types and sizes</a>. </td></tr><tr><td>81</td><td>MEDIA_SIZE_ERROR</td><td>Media size error.</td><td>Your media size is too large. Reference <a href="https://docs.clickatell.com/channels/one-api/supported-content-types/">this page</a> for guidelines.</td></tr><tr><td>82</td><td>MEDIA_CHECKSUM_FAILURE</td><td>Media checksum failure.</td><td></td></tr><tr><td>83</td><td>MEDIA_REJECTED_BY_SUPPLIER</td><td>Channel supplier rejected media file.</td><td>Ensure that media is present in your upload environment and that it adheres to <a href="/pages/QutiBlOdEvrMkvg0GP9a">supported media types and sizes</a>.</td></tr><tr><td>84</td><td>MEDIA_METADATA_ERROR</td><td>Metadata for the media file was not found or does not match the message request.</td><td>Please reference the <a href="/pages/G4lsIYFfKpIR9S108cwE">One API documentation</a> to ensure that all required metadata is present.</td></tr><tr><td>85</td><td>MEDIA_ACCESS_ERROR</td><td>An access/permissions-related error occurred when handling the media file.</td><td>Ensure that the media file is present and can be accessed by your system.</td></tr><tr><td>86</td><td>MEDIA_TYPE_NOT_SUPPORTED</td><td>The media type is not supported on the channel.</td><td>This specific media format is not supported on the channel. See <a href="/pages/QutiBlOdEvrMkvg0GP9a">here </a>for guidelines.</td></tr></tbody></table>

####

### SMS-specific

<table><thead><tr><th width="90">Status Code</th><th>Callbacks; Query Message Response (description presented to clients)</th><th>Short Description</th><th>Details</th></tr></thead><tbody><tr><td>100</td><td>ROUTING_ERROR</td><td>Routing error.</td><td>This SMS message did not route correctly.</td></tr></tbody></table>

####

### WhatsApp-specific

<table><thead><tr><th width="86">Status Code</th><th>Callbacks; Query Message Response (description presented to clients)</th><th>Short Description</th><th>Details</th></tr></thead><tbody><tr><td>130</td><td>WHATSAPP_ACCOUNT_PAYMENT_ISSUE</td><td>WhatsApp account payment issue.</td><td>There is a payment issue related to this account.</td></tr><tr><td>131</td><td>WHATSAPP_RE_ENGAGEMENT_REQUIRED</td><td>Re-engagement required.</td><td>The business must engage the client with an approved <a href="https://www.clickatell.com/help-center/whatsapp/message-templates/what-are-whatsapp-messages-templates/">message template</a> to initiate a new conversation.</td></tr><tr><td>132</td><td>WHATSAPP_SPAM_RATE_LIMIT_REACHED</td><td>Spam rate limit reached.</td><td>Relates to Whatsapp <a href="https://www.clickatell.com/help-center/whatsapp/message-templates/how-does-read-rate-impact-my-marketing-template-s-quality-rating/">Rate Limit and message quality</a>.</td></tr><tr><td>133</td><td>WHATSAPP_SERVER_RATE_LIMIT</td><td>WhatsApp server rate limit.</td><td>Your environment’s <a href="https://www.clickatell.com/help-center/whatsapp/message-templates/how-does-read-rate-impact-my-marketing-template-s-quality-rating/">rate limit</a> has been reached. Speak to your Technical Account Manager (TAM) about how to address this.</td></tr><tr><td>139</td><td>WHATSAPP_EXPERIMENTAL_NUMBER</td><td>Non-delivery due to WhatsApp experimental number feature.</td><td>Meta has initiated an experiment on this number.</td></tr><tr><td>140</td><td>WHATSAPP_TEMPLATE_TEXT_TOO_LONG</td><td>Length of the parameters and the template text exceeds the maximum allowed length.</td><td></td></tr><tr><td>141</td><td>WHATSAPP_TEMPLATE_FORMAT_MISMATCH</td><td>Specified template header is not in the expected format.</td><td>There is a problem with the template header. See here for guidelines. See <a href="https://guides.clickatell.com/whatsapp-channel/channel-capabilities/whatsapp-message-templates/add-message-templates">here</a> for guidelines on setting up message templates.</td></tr><tr><td>142</td><td>WHATSAPP_TEMPLATE_FORMATTING_POLICY_VIOLATED</td><td>Template header parameter formatting not allowed (bold, italic etc.).</td><td>There is a problem with the template header. See <a href="https://guides.clickatell.com/whatsapp-channel/channel-capabilities/whatsapp-message-templates/add-message-templates">here</a> for guidelines on setting up message templates.</td></tr><tr><td>143</td><td>WHATSAPP_TEMPLATE_MEDIA_FORMAT_UNSUPPORTED</td><td>Correct media type used in template, but the mime type is unsupported.</td><td></td></tr><tr><td>144</td><td>WHATSAPP_PARAMETER_MISSING</td><td>Required parameter is missing for this message.</td><td></td></tr><tr><td>145</td><td>WHATSAPP_PARAMETER_INVALID</td><td>A message parameter contains an invalid value.</td><td></td></tr><tr><td>146</td><td>WHATSAPP_PARAMETER_NOT_REQUIRED</td><td>A parameter was specified for the message that is not required.</td><td></td></tr><tr><td>147</td><td>WHATSAPP_TEMPLATE_INVALID_URL</td><td>Invalid hydrated URL received in template message.</td><td>Ensure that the URL used in the message template is valid.</td></tr><tr><td>148</td><td>WHATSAPP_TEMPLATE_INVALID_PHONE_NUMBER</td><td>Phone number in template message is missing.</td><td>Ensure that a valid telephone number is present in the message template.</td></tr><tr><td>149</td><td>WHATSAPP_TEMPLATE_RECEIVER_NO_BUTTON_SUPPORT</td><td>End-user device does not support buttons.</td><td></td></tr><tr><td>150</td><td>WHATSAPP_TEMPLATE_DOES_NOT_EXIST</td><td>The template does not exist in the specified language or has not been approved.</td><td>There is a problem with the template status. Review <a href="https://developers.facebook.com/docs/whatsapp/cloud-api/guides/send-message-templates/">these guidelines</a>.</td></tr><tr><td>151</td><td>WHATSAPP_TEMPLATE_PARAM_COUNT_MISMATCH</td><td>WhatsApp’s API indicated that the number of parameters provided does not match the expected number.</td><td>There is a problem with the template. Review <a href="https://developers.facebook.com/docs/whatsapp/cloud-api/guides/send-message-templates/">these guidelines</a>.</td></tr><tr><td>152</td><td>WHATSAPP_TEMPLATE_PAUSED</td><td>The template is in a paused status in the Meta account.</td><td>The template has been paused due to negative feedback from customers. Edit the template to improve <a href="https://www.clickatell.com/help-center/whatsapp/message-templates/how-does-read-rate-impact-my-marketing-templat">template quality</a>.</td></tr><tr><td>153</td><td>WHATSAPP_TEMPLATE_DISABLED</td><td>The template is in a disabled status in the Meta account.</td><td>The template has been disabled due to continuous poor feedback from customers. Please create a new template and follow <a href="https://guides.clickatell.com/whatsapp-channel/channel-capabilities/whatsapp-message-templates/message-templates-best-practices-and-examples">these recommendations</a>.</td></tr><tr><td>160</td><td>WHATSAPP_COMPLIANCE_INFO_MISSING</td><td>The business has not provided any compliance information.</td><td>Relevant to WhatsApp commerce messaging. Currently only applies to businesses in India.</td></tr><tr><td>161</td><td>WHATSAPP_PRODUCT_CATALOG_NOT_FOUND</td><td>The catalog ID you provided either does not exist, does not belong to your WhatsApp Business Account, or is not connected to the phone number you are using to send the message.</td><td>Relevant to WhatsApp commerce messaging. Review your catalog ID in Facebook Business Manager. See <a href="https://business.facebook.com/business/help/890714097648074?id=725943027795860">here</a> for guidelines.</td></tr><tr><td>162</td><td>WHATSAPP_PRODUCT_NOT_FOUND_IN_CATALOG</td><td>The product provided in a single-product message or all of the products provided in a multi-product message was not found in the catalog ID provided.</td><td>Relevant to WhatsApp commerce messaging. Review your catalog ID in Facebook Business Manager. See <a href="https://business.facebook.com/business/help/890714097648074?id=725943027795860">here</a> for guidelines.</td></tr><tr><td>163</td><td>WHATSAPP_PRODUCT_COMPLIANCE_ERROR</td><td>The product provided in a single-product message or all of the products provided in a multi-product message are missing or have incomplete e-commerce compliance information.</td><td><p>Relevant to WhatsApp commerce messaging. Currently only applies to businesses in India.</p><p>Review your catalog ID in Facebook Business Manager. See <a href="https://business.facebook.com/business/help/890714097648074?id=725943027795860">here</a> for guidelines.</p></td></tr><tr><td>170</td><td>WHATSAPP_MESSAGE_UNDELIVERABLE</td><td>Message undeliverable.</td><td><p></p><p>Your message has not been delivered. For WhatsApp, ensure:</p><ul><li>The end-user has WhatsApp installed on their phone.</li><li>The end-user did not block the specific business number.</li><li>The end-user has opted in to receive WhatsApp messages from the business.</li><li>The business is not spamming the end-user with marketing message templates that the client doesn’t respond to. Meta blocks messages in this scenario.</li></ul></td></tr><tr><td>171</td><td>WHATSAPP_CHOSE_NOT_TO_DELIVER</td><td>Meta chose not to deliver the message to maintain healthy ecosystem engagement.</td><td>Too many marketing messages are being sent to this number without engagement from the client.</td></tr></tbody></table>

####

### Generic status codes (payment-related)

| Status code | Callbacks; Query Message Response (description presented to clients) | Short Description          | Details                                                                    |
| ----------- | -------------------------------------------------------------------- | -------------------------- | -------------------------------------------------------------------------- |
| 283         | PAYMENT\_COMPLETED                                                   | Payment completed.         | Payment was completed successfully.                                        |
| 284         | PAYMENT\_DECLINED                                                    | Payment declined.          | Payment was not completed successfully.                                    |
| 285         | PAYMENT\_FAILED                                                      | Payment failed.            | A failure was encountered in the payment (not completed and not declined). |
| 286         | PAYMENT\_INVALID\_MERCHANT\_SESSION                                  | Invalid merchant session.  | A valid merchant session was not provided.                                 |
| 287         | PAYMENT\_INVALID\_WEBHOOK\_ENDPOINTS                                 | Invalid webhook endpoints. | Valid webhook endpoints were not provided.                                 |

## Errors Table

{% hint style="info" %}
If a user submitted more than one message and at least one was rejected, HTTP 207 is returned indicating that message-level responses must be looked at. This condition overrides the codes listed below.
{% endhint %}

<table><thead><tr><th width="79">Error Code</th><th width="101">HTTP Status Code</th><th width="268">Error Message</th><th width="85" data-type="checkbox">Global Level</th><th data-type="checkbox">Message Level</th></tr></thead><tbody><tr><td>1</td><td>401</td><td>Invalid or missing integration API Key</td><td>true</td><td>false</td></tr><tr><td>2</td><td>400</td><td>Account is not active</td><td>true</td><td>false</td></tr><tr><td>3</td><td>400</td><td>Integration is not active</td><td>true</td><td>false</td></tr><tr><td>7</td><td>401</td><td>Originating IP address is not approved in your account</td><td>true</td><td>false</td></tr><tr><td>18</td><td>500</td><td>Internal error</td><td>true</td><td>true</td></tr><tr><td>19</td><td>503</td><td>Internal error, please retry</td><td>true</td><td>true</td></tr></tbody></table>

####

### Generic errors (shared by all channels)

<table><thead><tr><th width="86">Error Code</th><th width="90">HTTP Status Code</th><th width="272">Error Message</th><th width="81" data-type="checkbox">Global Level</th><th data-type="checkbox">Message Level</th></tr></thead><tbody><tr><td>20</td><td>402</td><td>Insufficient account balance</td><td>false</td><td>true</td></tr><tr><td>21</td><td>400</td><td>Payload data is malformed</td><td>true</td><td>false</td></tr><tr><td>22</td><td>400</td><td>Maximum messages per request payload exceeded</td><td>true</td><td>false</td></tr><tr><td>23</td><td>400</td><td>Invalid or missing parameter: (parameter name)</td><td>false</td><td>true</td></tr><tr><td>24</td><td>400</td><td>Maximum message content size exceeded</td><td>false</td><td>true</td></tr><tr><td>25</td><td>400</td><td>Invalid recipient address: (MSISDN)</td><td>false</td><td>true</td></tr><tr><td>26</td><td>400</td><td>Recipient opted out</td><td>false</td><td>true</td></tr><tr><td>27</td><td>400</td><td>Recipient not available on channel</td><td>false</td><td>true</td></tr><tr><td>28</td><td>400</td><td>Recipient not available on sandbox</td><td>false</td><td>true</td></tr><tr><td>29</td><td></td><td><em>Reserved</em></td><td>false</td><td>false</td></tr><tr><td>30</td><td>400</td><td>Content type not supported</td><td>false</td><td>true</td></tr><tr><td>31</td><td>400</td><td>Media file size exceeds limit of xx MB</td><td>false</td><td>true</td></tr><tr><td>32</td><td>400</td><td>Media payload size exceeds limit of xx MB</td><td>false</td><td>true</td></tr><tr><td>33</td><td>400</td><td>Media item not found</td><td>false</td><td>true</td></tr><tr><td>34-37</td><td></td><td><em>Reserved</em></td><td>false</td><td>false</td></tr><tr><td>38</td><td>400</td><td>Channel/feature is not active on integration</td><td>false</td><td>true</td></tr><tr><td>39</td><td>400</td><td>Channel is not available on integration</td><td>false</td><td>true</td></tr><tr><td>40</td><td>400</td><td>Character set is not supported: (charset)</td><td>false</td><td>true</td></tr><tr><td>41</td><td>400</td><td>Resource does not exist</td><td>true</td><td>false</td></tr><tr><td>42</td><td>400</td><td>HTTP method is not supported on this resource</td><td>true</td><td>false</td></tr><tr><td>43</td><td>400</td><td>Rate limit</td><td>true</td><td>true</td></tr><tr><td>44</td><td>400</td><td>FROM number is suspended</td><td>false</td><td>true</td></tr><tr><td>45</td><td>400</td><td>FROM number is not related to integration</td><td>false</td><td>true</td></tr><tr><td>46</td><td>400</td><td>Demo access has expired</td><td>false</td><td>true</td></tr></tbody></table>

####

### SMS-specific

<table><thead><tr><th width="90">Error Code</th><th width="91">HTTP Status Code</th><th width="271">Error Message</th><th width="70" data-type="checkbox">Global Level</th><th data-type="checkbox">Message Level</th></tr></thead><tbody><tr><td>100</td><td>400</td><td>Maximum message parts exceeded</td><td>false</td><td>true</td></tr><tr><td>101</td><td>400</td><td>Destination does not support two-way messaging</td><td>false</td><td>true</td></tr><tr><td>110</td><td>400</td><td>USA country limit: must use two-way integration</td><td>false</td><td>true</td></tr><tr><td>111</td><td>400</td><td>USA country limit: must enable STOP/SUBSCRIBE commands on integration</td><td>false</td><td>true</td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.clickatell.com/developers-documentation/channels/whatsapp-and-sms-one-api/status-codes-and-errors.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.