Status Codes & Errors
View the description of possible status and error codes:
Message Status Table
Successful flow of messages
1
UNKNOWN
Message not found
The specified message was not found in the account. Please check the account details and message ID to ensure these are correct.
2
QUEUED
Message is queued
The message has been queued for delivery. This is a temporary status – please check again in a few hours.
3
SCHEDULED
Message scheduled for later delivery
The message is scheduled for later delivery. Review the message in a few hours to check on delivery.
4
SENT_TO_SUPPLIER
Sent to supplier
This message has been submitted to an external supplier. (For WhatsApp messages, this means Meta.)
5
DEVICE_ACK
Device acknowledged delivery
Two gray checkmarks on WhatsApp. The message was delivered successfully to the customer’s device. (WhatsApp-specific behavior)
6
READ
Read receipt
Two blue checkmarks on WhatsApp. The customer has read or opened the message. (WhatsApp-specific behavior)
Generic errors (shared by all channels)
20
EXPIRED
Message has expired.
Validity period or internal validity period-related.
21
STOPPED_BY_USER
Message stopped by the user.
22
STOPPED_BY
Message stopped by admin.
23
DELIVERY_FAILURE
Error delivering message.
Generic upstream supplier returned a permanent error. Could also be an internal error.
24
EMULATED
Emulated.
Used for sandbox messaging when the number being sent to has not been added as a test phone.
25
INSUFFICIENT_ACCOUNT_BALANCE
Insufficient account balance.
Review your account balance and ensure you have enough funds available.
26
VOLUME_LIMIT
Volume limit exceeded
27
VOLUME_LIMIT_DAILY
Daily volume limit exceeded.
Applies to the sandbox environment.
28
VOLUME_LIMIT_MONTHLY
Monthly volume limit exceeded.
Applies to the sandbox environment.
29
RECIPIENT_DOES_NOT_EXIST
Recipient does not exist on channel.
30
STOP_MARKETING_MESSAGES
Recipient does not want to receive marketing messages.
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.
31
EXCESSIVE_MESSAGES_SENT_TO_RECIPIENT
Your business sent too many messages to the recipient in a short period.
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.
Encryption-related
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.
Possible causes:
The media file was expected to have an encryptionKey field, but it was not present.
Mixing encrypted messages with non-encrypted media or vice versa.
Anonymous messaging status
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
80
MEDIA_NOT_FOUND
Media not found.
Ensure that media is present in your upload environment and that it adheres to supported media types and sizes.
81
MEDIA_SIZE_ERROR
Media size error.
Your media size is too large. Reference this page for guidelines.
82
MEDIA_CHECKSUM_FAILURE
Media checksum failure.
83
MEDIA_REJECTED_BY_SUPPLIER
Channel supplier rejected media file.
Ensure that media is present in your upload environment and that it adheres to supported media types and sizes.
84
MEDIA_METADATA_ERROR
Metadata for the media file was not found or does not match the message request.
Please reference the One API documentation to ensure that all required metadata is present.
85
MEDIA_ACCESS_ERROR
An access/permissions-related error occurred when handling the media file.
Ensure that the media file is present and can be accessed by your system.
86
MEDIA_TYPE_NOT_SUPPORTED
The media type is not supported on the channel.
This specific media format is not supported on the channel. See here for guidelines.
SMS-specific
100
ROUTING_ERROR
Routing error.
This SMS message did not route correctly.
WhatsApp-specific
130
WHATSAPP_ACCOUNT_PAYMENT_ISSUE
WhatsApp account payment issue.
There is a payment issue related to this account.
131
WHATSAPP_RE_ENGAGEMENT_REQUIRED
Re-engagement required.
The business must engage the client with an approved message template to initiate a new conversation.
132
WHATSAPP_SPAM_RATE_LIMIT_REACHED
Spam rate limit reached.
Relates to Whatsapp Rate Limit and message quality.
133
WHATSAPP_SERVER_RATE_LIMIT
WhatsApp server rate limit.
Your environment’s rate limit has been reached. Speak to your Technical Account Manager (TAM) about how to address this.
139
WHATSAPP_EXPERIMENTAL_NUMBER
Non-delivery due to WhatsApp experimental number feature.
Meta has initiated an experiment on this number.
140
WHATSAPP_TEMPLATE_TEXT_TOO_LONG
Length of the parameters and the template text exceeds the maximum allowed length.
141
WHATSAPP_TEMPLATE_FORMAT_MISMATCH
Specified template header is not in the expected format.
There is a problem with the template header. See here for guidelines. See here for guidelines on setting up message templates.
142
WHATSAPP_TEMPLATE_FORMATTING_POLICY_VIOLATED
Template header parameter formatting not allowed (bold, italic etc.).
There is a problem with the template header. See here for guidelines on setting up message templates.
143
WHATSAPP_TEMPLATE_MEDIA_FORMAT_UNSUPPORTED
Correct media type used in template, but the mime type is unsupported.
144
WHATSAPP_PARAMETER_MISSING
Required parameter is missing for this message.
145
WHATSAPP_PARAMETER_INVALID
A message parameter contains an invalid value.
146
WHATSAPP_PARAMETER_NOT_REQUIRED
A parameter was specified for the message that is not required.
147
WHATSAPP_TEMPLATE_INVALID_URL
Invalid hydrated URL received in template message.
Ensure that the URL used in the message template is valid.
148
WHATSAPP_TEMPLATE_INVALID_PHONE_NUMBER
Phone number in template message is missing.
Ensure that a valid telephone number is present in the message template.
149
WHATSAPP_TEMPLATE_RECEIVER_NO_BUTTON_SUPPORT
End-user device does not support buttons.
150
WHATSAPP_TEMPLATE_DOES_NOT_EXIST
The template does not exist in the specified language or has not been approved.
There is a problem with the template status. Review these guidelines.
151
WHATSAPP_TEMPLATE_PARAM_COUNT_MISMATCH
WhatsApp’s API indicated that the number of parameters provided does not match the expected number.
There is a problem with the template. Review these guidelines.
152
WHATSAPP_TEMPLATE_PAUSED
The template is in a paused status in the Meta account.
The template has been paused due to negative feedback from customers. Edit the template to improve template quality.
153
WHATSAPP_TEMPLATE_DISABLED
The template is in a disabled status in the Meta account.
The template has been disabled due to continuous poor feedback from customers. Please create a new template and follow these recommendations.
160
WHATSAPP_COMPLIANCE_INFO_MISSING
The business has not provided any compliance information.
Relevant to WhatsApp commerce messaging. Currently only applies to businesses in India.
161
WHATSAPP_PRODUCT_CATALOG_NOT_FOUND
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.
Relevant to WhatsApp commerce messaging. Review your catalog ID in Facebook Business Manager. See here for guidelines.
162
WHATSAPP_PRODUCT_NOT_FOUND_IN_CATALOG
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.
Relevant to WhatsApp commerce messaging. Review your catalog ID in Facebook Business Manager. See here for guidelines.
163
WHATSAPP_PRODUCT_COMPLIANCE_ERROR
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.
Relevant to WhatsApp commerce messaging. Currently only applies to businesses in India.
Review your catalog ID in Facebook Business Manager. See here for guidelines.
170
WHATSAPP_MESSAGE_UNDELIVERABLE
Message undeliverable.
Your message has not been delivered. For WhatsApp, ensure:
The end-user has WhatsApp installed on their phone.
The end-user did not block the specific business number.
The end-user has opted in to receive WhatsApp messages from the business.
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.
171
WHATSAPP_CHOSE_NOT_TO_DELIVER
Meta chose not to deliver the message to maintain healthy ecosystem engagement.
Too many marketing messages are being sent to this number without engagement from the client.
Generic status codes (payment-related)
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
1
401
Invalid or missing integration API Key
2
400
Account is not active
3
400
Integration is not active
7
401
Originating IP address is not approved in your account
18
500
Internal error
19
503
Internal error, please retry
Generic errors (shared by all channels)
20
402
Insufficient account balance
21
400
Payload data is malformed
22
400
Maximum messages per request payload exceeded
23
400
Invalid or missing parameter: (parameter name)
24
400
Maximum message content size exceeded
25
400
Invalid recipient address: (MSISDN)
26
400
Recipient opted out
27
400
Recipient not available on channel
28
400
Recipient not available on sandbox
29
Reserved
30
400
Content type not supported
31
400
Media file size exceeds limit of xx MB
32
400
Media payload size exceeds limit of xx MB
33
400
Media item not found
34-37
Reserved
38
400
Channel/feature is not active on integration
39
400
Channel is not available on integration
40
400
Character set is not supported: (charset)
41
400
Resource does not exist
42
400
HTTP method is not supported on this resource
43
400
Rate limit
44
400
FROM number is suspended
45
400
FROM number is not related to integration
46
400
Demo access has expired
SMS-specific
100
400
Maximum message parts exceeded
101
400
Destination does not support two-way messaging
110
400
USA country limit: must use two-way integration
111
400
USA country limit: must enable STOP/SUBSCRIBE commands on integration
Last updated