01 · Error Codes & Delivery Receipts

Voice Status Codes Reference

Quick reference for Voice API response status codes. For detailed explanations and troubleshooting guidance, see the Voice Status Codes Guide.

When You See These

Status codes are returned immediately in the API response when submitting a callflow to the Callflows API (POST /api/v1/subaccounts/{subaccountId}/callflows).

Status Codes

Status Code	Message
1	Created
-1001	Invalid JSON request body
-1002	Speech profile or language parameter invalid
-1003	Valid maxDigits required when minDigits provided
-1004	DTMF callback url not provided
-1005	Valid overallTimeout is required when digitTimeout provided
-1006	OverallTimeout should be greater than digitTimeout
-1007	Invalid action type was used
-1008	Valid maxDigits is required when completeOnHash is false
-1009	Invalid call flow entry provided
-1010	Some actions are provided beyond the allowed count
-1011	Multiple destination phone numbers found in the request
-1012	Invalid Callflow: Incorrect use of action Hangup
-1013	Invalid Callflow: First action should be a MakeCall action
-1014	Source or caller ID is not allowed
-1015	The validity period of the call flow request has expired
-1016	Invalid Callflow Content: Some special characters are invalid/unaccepted
-1017	Invalid MSISDN format in Destination
-1018	Invalid Callflow: Execute Scenario cannot be processed together with other actions
-1019	Invalid Callflow Content: scenarioName is null or empty
-1020	Invalid Callflow: Invalid scenarioName or account doesn't have permission
-9999	An unknown error has occurred

When You See These

Error codes appear in the Voice Session Summary (VSS) webhook after a voice session has ended or failed. These indicate problems during call execution, not API validation issues.

Error Codes

Error Code	Description
-2001	An internal error has occurred
-2002	An internal connectivity error has occurred
-2003	The call flow provided is invalid
-2004	No coverage available for requested area
-2005	Unable to synthesize text to speech
-2006	Unable to download file for playback
-2007	The validity period of the call flow request has expired
-2008	The provided source MSISDN or caller ID is not whitelisted
-2009	The scenario parameters provided is invalid
-2010	The trunk capacity has been exceeded
-9999	An unknown error has occurred

Overview

Voice error codes are reported in the Voice Session Summary (VSS) webhook when errors occur during call execution. Unlike status codes which are returned immediately in the API response, these error codes indicate problems that happened while the call was being processed.

When you receive these codes:

In the Voice Session Summary (VSS) webhook
After the voice session has ended or failed
In the errorDetails field or related error information in the VSS payload

What they indicate:

Internal system errors
Connectivity or routing issues
Problems with callflow execution (TTS, file playback, etc.)
Capacity or permission restrictions

Applicable To

These error codes apply to all voice products using the 8x8 Voice Platform:

Interactive Voice Response (IVR)
Voice Messaging
Number Masking (see also Number Masking-specific error codes)
Any voice application using callflows

Error Codes

Error Code	Description
-2001	An internal error has occurred
-2002	An internal connectivity error has occurred
-2003	The call flow provided is invalid
-2004	No coverage available for requested area
-2005	Unable to synthesize text to speech
-2006	Unable to download file for playback
-2007	The validity period of the call flow request has expired
-2008	The provided source MSISDN or caller ID is not whitelisted
-2009	The scenario parameters provided is invalid
-2010	The trunk capacity has been exceeded
-9999	An unknown error has occurred

Overview

Status codes and status messages are returned in the API response when you submit a callflow to the Callflows API. These codes indicate whether your callflow request was successfully accepted and a session was created, or if there were validation errors in your request.

When you receive these codes:

Immediately after submitting a callflow via the Callflows API
As part of the API response body

What they indicate:

Status Code 1 with "CREATED" status - Your callflow passed validation and a session was created
Negative status codes with "NOT_CREATED" status - Your callflow has validation errors and was rejected

Note: These are API validation codes. Execution errors that occur during the call will be reported via the Voice Session Summary (VSS) webhook, not in the initial API response.

Applicable To

These status codes apply to all products using the Callflows API:

Interactive Voice Response (IVR)
Voice Messaging
Any voice application using callflow submissions

Status Codes and Messages

Status Code	Message
1	Created
-1001	Invalid JSON request body
-1002	Speech profile or language parameter invalid
-1003	Valid maxDigits required when minDigits provided
-1004	DTMF callback url not provided
-1005	Valid overallTimeout is required when digitTimeout provided
-1006	OverallTimeout should be greater than digitTimeout
-1007	Invalid action type was used. Accepted action type is [say, sayAndcapture, makeCall, hangup, playFile]
-1008	Valid maxDigits is required when completeOnHash is false
-1009	Invalid call flow entry provided. [Additional error details here]. Eg: Invalid call flow entry provided. $.callflow[0].params.text: is missing but it is required
-1010	Some actions are provided beyond the allowed count
-1011	Multiple destination phone numbers found in the request
-1012	Invalid Callflow : Incorrect use of action Hangup
-1013	Invalid Callflow : First action should be a MakeCall action
-1014	Source or caller ID is not allowed
-1015	The validity period of the call flow request has expired
-1016	Invalid Callflow Content: Some special characters are invalid/unaccepted
-1017	Invalid MSISDN format in Destination
-1018	"Invalid Callflow: " or "Execute Scenario cannot be processed together with other actions
-1019	Invalid Callflow Content: scenarioName is null or empty
-1020	Invalid Callflow: Invalid scenarioName or the account doesn't have permission to execute this scenario
-9999	An unknown error has occurred.

Source: https://developer.8x8.com/connect/docs/status-error-code · 8x8 CPaaS Developer Docs. Synced for support deflection.

SMPP - Delivery receipts
SMPP - Delivery receipts

8x8 sends delivery report information in the short_message field of a deliver_sm PDU.

The following format should be expected:

Format

id:IIIIIIIIII sub:SSS dlvrd:DDD submit date:YYMMDDhhmm done date:YYMMDDhhmm stat:DDDDDDD err:E Text: . . . . . . . . .

Where:

stat: is one of the message states below

err: is one of the error codes below, if available.

Message States

The following message states can be found in a delivery report:

DELIVRD

EXPIRED

UNDELIV

ACCEPTD

UNKNOWN

ENROUTE

REJECTD

Error Codes

For the list of error codes that might be sent in DLR please refer to SMS Delivery receipts error codes
Source: https://developer.8x8.com/connect/docs/smpp-delivery-receipts · 8x8 CPaaS Developer Docs. Synced for support deflection.

Number Lookup Error Codes

The 8x8 Number Lookup API uses the following error codes:

HTTP Status Code	Reason
2000	Internal error / Unknown provider error
2004	Provider Timeout
2005	Provider Error
2006	The pricing plan for that request plan is not configured for particular SubAccount
2007	Billing error. Not enough Account balance
6000	Live lookup on destination operator is currently not available
6001	SIM card is offline
6002	Mobile subscriber not reachable
6003	SIM card is deactivated
6004	Routing error
6005	SIM card is full

Source: https://developer.8x8.com/connect/docs/number-lookup-error-codes · 8x8 CPaaS Developer Docs. Synced for support deflection.

Number Masking Error Codes

Overview

Number Masking error codes are reported in Number Masking-specific callbacks and session summaries when errors occur during call bridging sessions. These codes help diagnose issues specific to Number Masking scenarios such as privacy-protected call routing, virtual number handling, and two-party call bridging.

When you receive these codes:

In the Session Summary (Number Masking) webhook
In the Call Status (Number Masking) webhook
After a Number Masking session has ended or failed
In the errorDetails field of the webhook payload when sessionStatus is "ERROR"

What they indicate:

Call bridging and routing failures
Virtual number configuration issues
Privacy protection enforcement problems
Network connectivity or coverage limitations specific to masked call routing

Related documentation:

For general voice errors applicable across all voice products, see Voice Error Codes
For API validation errors, see Voice Status Codes and Status Messages
For Number Masking implementation guides, see Getting Started with Number Masking

Applicable To

These error codes are specific to Number Masking (call bridging) scenarios:

Anonymous call routing between two parties
Privacy-protected communication sessions
Virtual number-based call forwarding
Two-leg call bridging implementations

Error Codes

Error Code	Message
-2001	An internal error has occurred
-2002	An internal connectivity error has occurred
-2003	The call flow provided is invalid
-2004	No coverage available for requested area
-2005	Unable to synthesize text to speech
-2006	Unable to download file for playback
-2007	The validity period of the call flow request has expired
-2008	The provided source MSISDN or caller ID is not whitelisted
-2009	The scenario parameters provided is invalid
-2010	The trunk capacity has been exceeded
-9999	An unknown error has occurred

Troubleshooting Common Number Masking Errors

Error -2004: No coverage available for requested area

This error typically occurs when attempting to route calls to or from regions not supported by your Number Masking configuration. Verify that both caller and callee regions are within your account's coverage area.

Error -2007: Validity period expired

Number Masking sessions have a validity period to ensure privacy and security. This error indicates the session expired before the call could be established. Consider adjusting your session timeout settings or implementing retry logic.

Error -2008: Source MSISDN not whitelisted

For privacy and fraud prevention, Number Masking requires caller IDs to be whitelisted. Ensure all source numbers used in your Number Masking flows are registered and approved for your account.

Error -2010: Trunk capacity exceeded

This indicates your concurrent call limit has been reached. Contact your account manager to review capacity requirements and adjust limits if needed.

Source: https://developer.8x8.com/connect/docs/error-codes-number-masking · 8x8 CPaaS Developer Docs. Synced for support deflection.

Delivery receipts for outbound SMS

Delivery Receipts (DR) are webhooks for delivery statuses: POST requests sent by 8x8 platform in JSON format to the delivery reports callback URL configured for your account.

Whenever a message has a new delivery status associated with the delivery stage it is in, 8x8 sends out a POST request with the new status to the callback URL.

📘

You can configure your callback using Webhooks Configuration API

You can also overwrite the default callback URL on a per-message / per-batch-of-message basis by specifying a different dlrCallbackUrl value in your API requests when sending a message or a batch of messages (see Send API)

Retry logic

In case of connection error/timeout or HTTP response code 4XX or 5XX, there will be multiple retry attempts with progressive intervals: 1, 10, 30, 90 sec.

Delivery Receipt - Validity Period

If we do not receive a delivery receipt from the SMS carrier promptly, our platform will continue checking for up to 48 hours for a delivery receipt. If the delivery receipt is received after this 48-hour period, there will be no delivery receipt webhook sent.

Webhook format

Request body description

Parameter name	Parameter type	Description
namespace	string	A generic namespace for incoming webhook. Equal to `SMS` for delivery receipts.
eventType	string	Webhook type. Equals to `outbound_message_status_changed` for delivery receipts.
description	string	Human-readable description of the incoming event
payload	object	Delivery receipt information, see below.

Payload object description

Parameter name	Parameter type	Description
umid	uuid	A unique identifier generated by 8x8 for the message
batchId	uuid	A unique identifier generated by 8x8 for the message if sent using Batch API
clientMessageId	string	Your custom identifier for the message
clientBatchId	string	Client managed id for this batch of messages : your own unique reference
subAccountId	string	The sub-account id used to deliver the message
source	string	The source (i.e: sender) used to deliver the message
destination	string	Destination phone number where the SMS was sent (E.164 format)
status	object	Current status of the message, please see Message status reference for details.
price	object	Price information of the message, this field is optional in the response if there is no charge incurred. Please see Price object reference for details
smsCount	integer	Number of SMS segment in the message

🚧

Please note that the Price object is optional and might not be included in the Delivery Receipts callback. When a message was not sent successfully, you will still receive Delivery Receipts with Failed/Undelivered status without incurring any charges. Hence, the price information is not available for the Delivery Receipts.

❗️

If the request you receive has a different structure from described in this document, please contact our support to activate the latest format for your account.

Sample delivery receipt for outbound SMS

{
"namespace":"SMS",
"eventType":"outbound_message_status_changed",
"description":"SMS outbound message delivery receipt",
"payload":{
"umid":"9e09ac86-bd74-5465-851d-1eb5a5fdbb9a",
"batchId":"3e09ac86-bd74-5465-851d-1eb5a5fdbb9b",
"clientMessageId":"1e09ac86-bd74-5465-851d-1eb5a5fdbb9b",
"clientBatchId":"2e09ac86-bd74-5465-851d-1eb5a5fdbb9b",
"subAccountId":"SubAccount-1",
"source":"8x8",
"destination":"+12025550293",
"status":{
"state":"undelivered",
"detail":"rejected_by_operator",
"timestamp":"2016-01-01T00:00:00Z",
"errorCode":15,
"errorMessage":"Invalid destination"
},
"price":{
"total":0.0375,
"perSms":0.0125,
"currency":"USD"
},
"smsCount":3
}
}

<?xml version="1.0" encoding="UTF-8" ?>
<root>
<namespace>SMS</namespace>
<eventType>outbound_message_status_changed</eventType>
<description>SMS outbound message delivery receipt</description>
<payload>
<umid>9e09ac86-bd74-5465-851d-1eb5a5fdbb9a</umid>
<batchId>3e09ac86-bd74-5465-851d-1eb5a5fdbb9b</batchId>
<clientMessageId>1e09ac86-bd74-5465-851d-1eb5a5fdbb9b</clientMessageId>
<clientBatchId>2e09ac86-bd74-5465-851d-1eb5a5fdbb9b</clientBatchId>
<subAccountId>SubAccount-1</subAccountId>
<source>8x8</source>
<destination>+12025550293</destination>
<status>
<state>undelivered</state>
<detail>rejected_by_operator</detail>
<timestamp>2016-01-01T00:00:00Z</timestamp>
<errorCode>15</errorCode>
<errorMessage>Invalid destination</errorMessage>
</status>
<price>
<total>0.0375</total>
<perSms>0.0125</perSms>
<currency>USD</currency>
</price>
<smsCount>3</smsCount>
</payload>
</root>

Source: https://developer.8x8.com/connect/docs/delivery-receipts-for-outbound-sms · 8x8 CPaaS Developer Docs. Synced for support deflection.

Delivery receipts for Outbound Messaging Apps

Delivery Report (DR) are webhooks for Messaging Apps delivery statuses: POST requests sent by the 8x8 platform in JSON format to the callback URL configured for your account.

Requirements

To use 8x8 Outbound Messaging Apps capabilities, you need:

An account configured to use Messaging Apps product.
A webhook to indicate to us which URL 8x8 platform should send delivery reports to.

📘

You can configure your callback using Webhooks Configuration API

Retry logic

In case of connection error/timeout or HTTP response code 4XX or 5XX, there will be multiple retry attempts with progressive intervals: 1, 10, 30, 90 sec.

Read Receipt - Validity Period

If the chat app doesn't provide a read receipt promptly, either because the user hasn't read the message or due to a chat app service issue, we'll continue checking for up to 10 days. If the user reads the message after this period, the read receipt won't be updated.

Webhook format

Request body description

Parameter name	Parameter type	Description
namespace	string	A generic namespace for incoming webhook. Equal to `ChatApps` for delivery receipts.
eventType	string	Webhook type. - `outbound_message_status_changed` for delivery receipts - `external_app_message` for WhatsApp Business App messages
description	string	Human-readable description of the incoming event
payload	object	Delivery receipt information, see below

Payload object description

Parameter name	Parameter type	Description
umid	uuid	A unique identifier generated by 8x8 for the message
batchId	uuid	A unique identifier generated by 8x8 for the message if sent using Batch API
clientMessageId	string	Custom identifier you provided for this message
clientBatchId	string	Custom identifier you provided for this batch of messages
subAccountId	string	The sub-account id used to deliver the message
timestamp	string	UTC date and time when the message was sent expressed in ISO 8601 format. Only present when `eventType=external_app_message`
channel	string	Name of the channel used to send the message, please see List of supported Messaging Apps channels for details
user	object	Information about the user the message is associated with
type	string	Message type. See Inbound Messaging Apps message type field for possible values. Only present when `eventType=external_app_message`
content	object	Message content. Structure varies based on the `type` field. Only present when `eventType=external_app_message`
status	object	Current status of the message, please see Message status reference for details. Only present when `eventType=outbound_message_status_changed`
whatsapp	object	WhatsApp-specific information. Only present when `channel` is `whatsapp`. See below for details

User information object description

Parameter name	Parameter type	Description
msisdn	string	Phone number expressed in E.164 international format
channelUserId	string	Channel user identifier

WhatsApp object description

Parameter name	Parameter type	Description
providerErrorCode	string	WhatsApp's own error code. Only present if there was an error
pricingCategory	string	WhatsApp's pricing category as defined by Meta. Only included with sent status, and one of either delivered or read status

🚧

Please note that unlike Delivery Receipts for the SMS API, the Price object is not sent for Messaging Apps Webhooks.

❗️

If the request you receive has a different structure from described in this document, please contact our support to activate the latest format for your account.

Sample delivery receipt for outbound message

{
"namespace":"ChatApps",
"eventType":"outbound_message_status_changed",
"description":"ChatApps outbound message delivery receipt",
"payload":{
"umid":<UNIQUE_MESSAGE_ID>,
"batchId":<BATCH_ID>,
"clientMessageId":<YOUR_MESSAGE_ID>,
"clientBatchId":<YOUR_BATCH_ID>,
"subAccountId":<SUBACCOUNT_ID>,
"channel":"whatsapp",
"user":{
"msisdn":"+6512345678",
"channelUserId":"6512345678"
},
"status":{
"state":"delivered",
"detail":"delivered_to_recipient",
"timestamp":"2025-05-05T09:15:57.00Z"
},
"whatsapp":{
"pricingCategory":"marketing"
}
}
}

{
"namespace":"ChatApps",
"eventType":"outbound_message_status_changed",
"description":"ChatApps outbound message delivery receipt",
"payload":{
"umid":<UNIQUE_MESSAGE_ID>,
"batchId":<BATCH_ID>,
"clientMessageId":<YOUR_MESSAGE_ID>,
"clientBatchId":<YOUR_BATCH_ID>,
"subAccountId":<SUBACCOUNT_ID>,
"channel":"whatsApp",
"user":{
"msisdn":"+6512345678",
"channelUserId":"6512345678"
},
"status":{
"state":"read",
"timestamp":"2025-05-17T06:27:52.45Z"
},
"whatsapp":{
"pricingCategory":"marketing"
}
}
}

{
"namespace":"ChatApps",
"eventType":"outbound_message_status_changed",
"description":"ChatApps outbound message delivery receipt",
"payload":{
"umid":<UNIQUE_MESSAGE_ID>,
"batchId":<BATCH_ID>,
"clientMessageId":<YOUR_MESSAGE_ID>,
"clientBatchId":<YOUR_BATCH_ID>,
"subAccountId":<SUBACCOUNT_ID>,
"channel":"whatsapp",
"user":{
"msisdn":"+6512345678",
"channelUserId":"+6512345678"
},
"status":{
"state":"undelivered",
"detail":"rejected_by_operator",
"timestamp":"2016-01-01T00:00:00Z",
"errorCode":15,
"errorMessage":"Invalid destination"
},
"whatsapp":{
"providerErrorCode":"131009"
}
}
}

WhatsApp Business App Messages

When using WhatsApp with Embedded Signup, messages sent by your business through the WhatsApp Business App are forwarded to your configured webhook as external_app_message events. This allows you to track all outbound messages sent on behalf of your business through the WhatsApp Business App.

📘

For more information, see WhatsApp's Embedded Signup documentation.

Key differences from delivery receipts:

eventType is external_app_message instead of outbound_message_status_changed
Includes timestamp, type, and content fields in the payload (see webhook format above)
Does not include status, batchId, clientMessageId, or clientBatchId fields

Sample WhatsApp Business App message webhook

{
"namespace":"ChatApps",
"eventType":"external_app_message",
"description":"External App Message",
"payload":{
"umid":"20a5347f-6898-4f39-86ef-b3e100b50929",
"subAccountId":"integration_test_whatsapp",
"timestamp":"2026-01-28T09:16:53.00Z",
"channel":"whatsapp",
"user":{
"msisdn":"+16505551234",
"channelUserId":"16505551234"
},
"type":"Text",
"content":{
"text":"Here's the info you requested! https://www.meta.com/quest/quest-3/"
}
}
}

Source: https://developer.8x8.com/connect/docs/delivery-receipts-for-outbound-chatapps · 8x8 CPaaS Developer Docs. Synced for support deflection.

SMS Delivery Receipt Error Codes

ℹ️ Troubleshooting tip

The table below lists delivery receipt error codes for SMS
If you are debugging an error that appears in the JSON body of an 8x8 API response (for example "code": 1200), please see the API Error Codes reference instead.

Subject to enhanced details available on from outbound route, the following error codes can be sent by 8x8 in the delivery reports

Code	Reason
0	No reason code
1	Absent subscriber
2	Content related error
3	Data missing
4	Deferred delivery
5	Pending upstream
7	Delivery failure
8	Deny
9	Equipment protocol error
10	ESME external error
11	Flooding
12	HLR error
13	Illegal subscriber or equipment
14	Internal error
15	Invalid destination
16	Invalid format
17	Invalid message length
18	Invalid parameter
19	Invalid source address
20	Local cancel
21	Memory capacity exceeded
22	Message being retried
23	Network failure
24	Age verification failure
25	Operation aborted by receiving network or user
26	Operation barred
27	Permanent operator error
28	Permanent phone error
29	Phone related error
30	Portability error
31	Premium SMS error
32	Roaming subscriber
33	Route error
34	Screening error
35	Service center congestion
36	SMS expired
37	SMS facility not supported
38	SMS malformed
39	SMSC cancel
40	SMSC error
41	SMSC reject
42	Source credit insufficiency
43	Spam filter
44	Subscriber billing issue
45	Subscriber busy for SMS
46	Subscriber not reachable
47	Subscriber temporary unavailable
48	System failure
49	TCAP error
50	Throttling error
51	Time out error
52	Unable to decode the response
53	Unexpected data value
54	Unexpected error
55	Unidentified subscriber
56	Unknown delivery state
57	Unknown error
58	Unknown service center
59	Unknown subscriber
60	Content filtered
61	Session expired

Source: https://developer.8x8.com/connect/docs/delivery-receipts-error-codes · 8x8 CPaaS Developer Docs. Synced for support deflection.

Messaging Apps Delivery Receipt Error Codes

ℹ️ Troubleshooting tip

The table below lists delivery receipt error codes for Messaging Apps
If you are debugging an error that appears in the JSON body of an 8x8 API response (for example "code": 3038), please see the API Error Codes reference instead.

Possible error codes returned in the Messaging Apps delivery receipts include:

General Error Codes

Code	Possible reason	Description
1	AbsentSubscriber	Subscriber is not registered in this chat channel
2	ContentRelatedError	Content Type is not supported by this channel
3	DataMissing	The request is missing a required parameter
9	EquipmentProtocolError	The receiver's app version is not capable of receiving business messages
11	Flooding	Too many messages sent to the recipient in a short period of time
14	InternalError	Internal error
15	InvalidDestination	UserId is not valid for that channel or is part of blacklist on Connect
18	Invalid parameter	Invalid or missing parameters. Check that all required parameters are passed and are of the correct type
23	ConnectionError	Channel connection error
25	Operation Aborted By Receiving Network Or User	Message is intentionally undelivered by Channel
29	PhoneRelatedError	The specified parameter value is invalid
36	Expired	Message expired (not delivered at the requested time)
41	SmscReject	Message rejected by Chat channel
42	NoCredit	Not enough credit on Account wallet
43	SpamFilter	Message filtered by anti-spam reason
46	SubscriberNotReachable	Message sent to Channel, but user is not reachable for delivery
57	UnknownError	An unknown error occurred with no more specific reason available
61	SessionExpired	Message trashed by session expired reason

WhatsApp Error Codes

Code	Possible Reasons	Description
1000	Authentication failed	AuthException — Unable to authenticate app user (WhatsApp: 0)
1001	Method not allowed	API Method — Capability/permissions issue (WhatsApp: 3)
1002	Rate limit exceeded	API Too Many Calls — App rate limit reached (WhatsApp: 4)
1003	Permission missing	Permission Denied — Permission not granted or removed (WhatsApp: 10)
1004	Invalid value	Parameter value not valid — Business phone number deleted (WhatsApp: 33)
1005	Invalid parameter	Invalid parameter — Misspelled or unsupported parameter (WhatsApp: 100)
1006	Token expired	Access token expired (WhatsApp: 190)
1007	Policy violation	Temporarily blocked for policy violations (WhatsApp: 368)
1008	Rate limit hit	WABA rate limit reached (WhatsApp: 80007)
1009	Throughput exceeded	Rate limit hit — Message throughput limit reached (WhatsApp: 130429)
1010	Experimental number	Number part of experiment (WhatsApp: 130472)
1011	Region restriction	Business account restricted in this country (WhatsApp: 130497)
1012	Unknown failure	Something went wrong — Unknown error (WhatsApp: 131000)
1013	Access denied	Access denied — Permission not granted (WhatsApp: 131005)
1014	Missing parameter	Required parameter is missing (WhatsApp: 131008)
1015	Invalid parameter value	Parameter value is not valid (WhatsApp: 131009)
1016	Service down	Service unavailable — Temporary service downtime (WhatsApp: 131016)
1017	Sender = Receiver	Recipient cannot be sender (WhatsApp: 131021)
1018	Message rejected	Message undeliverable (WhatsApp: 131026)
1019	Account locked	Account locked (WhatsApp: 131031)
1020	Display name not approved	Display name approval needed (WhatsApp: 131037)
1021	Bad certificate	Incorrect certificate (WhatsApp: 131045)
1022	Message window expired	Re-engagement message (outside 24-hour window) (WhatsApp: 131047)
1023	Spam control triggered	Spam rate limit hit (WhatsApp: 131048)
1024	Message suppressed	Meta chose not to deliver (WhatsApp: 131049)
1025	Unsupported message	Unsupported message type (WhatsApp: 131051)
1026	Download failed	Media download error (WhatsApp: 131052)
1027	Upload failed	Media upload error (WhatsApp: 131053)
1028	Sender-recipient throttled	Sender/recipient pair rate limit hit (WhatsApp: 131056)
1029	Account under maintenance	Account in maintenance mode (WhatsApp: 131057)
1030	Wrong number of params	Template param count mismatch (WhatsApp: 132000)
1031	Template missing	Template does not exist (WhatsApp: 132001)
1032	Text too long	Template hydrated text too long (WhatsApp: 132005)
1033	Template violation	Template policy violation (WhatsApp: 132007)
1034	Wrong param format	Template param format mismatch (WhatsApp: 132012)
1035	Template paused	Template paused (WhatsApp: 132015)
1036	Template disabled	Template disabled (WhatsApp: 132016)
1037	Flow blocked	Flow blocked (WhatsApp: 132068)
1038	Flow throttled	Flow throttled (WhatsApp: 132069)
1039	Deregistration failed	Incomplete deregistration (WhatsApp: 133000)
1040	Server unavailable	Server temporarily unavailable (WhatsApp: 133004)
1041	PIN mismatch	Two-step PIN mismatch (WhatsApp: 133005)
1042	Reverification required	Phone number re-verification needed (WhatsApp: 133006)
1043	Too many guesses	Too many two-step PIN guesses (WhatsApp: 133008)
1044	PIN entry too fast	Two-step PIN guessed too fast (WhatsApp: 133009)
1045	Number not registered	Phone number not registered (WhatsApp: 133010)
1046	Retry after delay	Wait before registering phone number (WhatsApp: 133015)
1047	Too many attempts	Account register/deregister limit exceeded (WhatsApp: 133016)
1048	Unknown client-side issue	Generic user error (WhatsApp: 135000)
1049	Too many sync calls	Synchronisation request limit exceeded (WhatsApp: 2593107)
1050	Sync time expired	Synchronisation request outside allowed time window (WhatsApp: 2593108)
1051	Message can't be delivered	The recipient has opted-out of receiving marketing messages from your business (WhatsApp: 131050)

Viber Error Codes

Code	Possible Reasons	Description
2000	Successfully sent	Message sent successfully
2001	Internal server error	Internal processing failure
2002	Invalid service ID	Service ID unused or not yet uploaded
2003	Bad request structure	Malformed request (e.g. JSON formatting)
2004	Incorrect message type	Unsupported or invalid message type
2005	Missing parameters	Required field like tracking_data is missing
2006	Timeout	Viber server timeout
2007	User blocked	User has blocked this ID or all business messages
2008	Not a Viber user	Destination number not registered with Viber
2009	No suitable device	Device not compatible with Business Messages
2010	Unauthorized IP or ID	Wrong IP or ID not whitelisted
2012	Bad label	Missing or invalid 'label' parameter
2013	Invalid TTL	TTL is out of allowed range
2014	Session message limit reached	Exceeded 10-message session cap
2015	Unsupported file format	File type not allowed for this feature
2016	Filename too long	File name exceeds 25 character limit
2017	Thumbnail too long	Thumbnail URL exceeds 1000 characters
2018	File too large	File size exceeds 200 MB
2019	Video too long	Video duration exceeds 600 seconds
2020	Template ID not found	The provided template ID is not found
2021	Template validation failed	Template variables did not pass the server validation
2022	Incompatible with Version	Version is not compatible to the message fields
2023	Invalid destination number	The destination number is invalid or does not exist. Please verify the destination phone number and try again
2024	Invalid List Message Parameter	Message delivery failed because one or more List Message parameters are invalid
2025	Invalid Carousel Message Parameter	Message delivery failed because one or more Carousel Message parameters are invalid

Source: https://developer.8x8.com/connect/docs/delivery-error-codes · 8x8 CPaaS Developer Docs. Synced for support deflection.

API Error codes

ℹ️ Troubleshooting tip

This page documents platform level API error codes returned in 8x8 API responses.

For delivery related errors coming back after we hand messages to suppliers, see the Messaging Apps Delivery Receipt Error Codes reference and SMS Delivery Receipt Error Codes

HTTP Error Codes

8x8 API might return the following HTTP error codes:

Code	Description
200	OK, The request has succeeded.
201	Created, The request has succeeded and a new resource has been created as a result.
202	Accepted, The request has been received but not yet acted upon.
204	No Content, The request has succeeded, but there is no content to send as a response.
400	Bad Request, Request has invalid syntax.
401	Unauthorized, The client must provide the correct API key in the `Authorization` header.
403	Forbidden, The client is authenticated but does not have permissions to the content
404	Not Found, The server can not find the requested resource.
410	Gone, The requested content has been permanently deleted from the server, with no forwarding address. This usually applied to the API version that's not supported anymore.
422	422 Unprocessable Entity, The request was well-formed but was unable to be followed due to semantic errors.
426	Upgrade Required, The client is using an unsupported TLS version. Upgrade to TLS 1.3 or higher. The response includes an `Upgrade: TLS/1.3` header.
429	Too Many Requests, The user has sent too many requests in a given amount of time ("rate limiting").
500	Internal Server Error, The server has encountered a situation it doesn't know how to handle.

All API responses with HTTP code 400 and above has the following properties:

code (integer) - Error code
message (string) - Human-readable error description
errorId (UUID) - Unique id of the error. You can use it as a reference when sending inquiries to 8x8 support.
timestamp (string, date-time) - Date and time of the error occurrence. Format: yyyy-MM-ddTHH:mm:ss.ffZ

Example of error JSON object returned by the API

{
"code":1300,
"message":"Object wasn't found or is already expired",
"errorId":"1cc1eda1-f5dd-ea11-8288-0263195dd35a",
"timestamp":"2020-12-22T05:52:01.85Z"
}

API Response Property Values

The table below refers to the possible values of the "code" parameter, in the response body returned by the API as shown above. They can be used for additional clarity of what type of error was encountered.

SMS API, Messaging API

Code	Description
1000	Invalid parameter
1001	Illegal SubAccountId
1002	Invalid MSISDN
1003	Invalid Encoding
1004	Invalid Text
1005	Invalid Source
1006	Invalid Expiry
1007	Invalid SMS Template
1008	Invalid ID
1009	Invalid Country Code
1010	Parameter out of range
1011	Invalid Schedule Time
1012	Invalid Ip Address
1014	Insecure Protocol — unsupported TLS version
1100	Bulk limit reached
1200	Unauthorized Access
1201	Access forbidden
1300	Not found
1400	Resending interval violation
2000	Internal Error
2001	Function not implemented
2002	Unsupported API version
2003	Unsupported product
3001	Missed User
3002	Missed MSISDN
3003	Invalid MSISDN
3004	Missed Content
3005	Missed Text
3006	Too long text
3007	Missed Media URL
3008	Invalid Media URL
3009	Too long ClientMessageId
3010	Invalid Content Type
3011	Too long SMS Source
3012	Missed messages
3013	Too much messages
3014	Too long ClientBatchId
3015	Missed UserId
3016	Missed WeChatUserId
3017	Too long Fallback text
3018	Invalid Country code
3019	Missed FacebookUserId
3020	Invalid DR Callback URL
3021	Empty or Invalid Location
3022	Invalid Fallback Channel
3023	Invalid Fallback Delay range
3024	Invalid Fallback Status
3025	Invalid Fallback Status Delivered
3026	Invalid Fallback Status Read
3027	Invalid Fallback SubAccount Channel
3028	Missed ZaloUserId
3029	Missed UMID
3030	Empty Template
3031	Invalid Template Name Length
3032	Invalid Template Name
3033	Too much template parameters passed
3034	Invalid template components combination
3035	SubAccount don’t have channels, supported templates
3036	Empty Template language
3037	Invalid Template language
3038	Template not found
3039	Invalid Template Component type
3040	Empty template parameters
3041	Invalid Template parameter
3042	Invalid Template parameter type
3043	Template Text parameter length exceeded
3044	Template Location parameter empty
3045	Template parameter not allowed
3046	Template parameter URL is invalid
3047	Missed WhatsApp UserID
3048	Using ChatGroupId with UserId not allowed
3049	Invalid button parameter
3050	Missed KakaoId
3051	Invalid Fallback ChannelID
3052	Invalid Template Component SubType
3053	Invalid index
3060	Template is being deleted. Learn more

Source: https://developer.8x8.com/connect/docs/api-error-codes · 8x8 CPaaS Developer Docs. Synced for support deflection.

When You See These

Status Codes

Related Documentation

When You See These

Error Codes

Related Documentation

Overview

Applicable To

Error Codes

Related Documentation

Overview

Applicable To

Status Codes and Messages

Format

Message States

Error Codes

Overview

Applicable To

Error Codes

Troubleshooting Common Number Masking Errors

Error -2004: No coverage available for requested area

Error -2007: Validity period expired

Error -2008: Source MSISDN not whitelisted

Error -2010: Trunk capacity exceeded

Retry logic

Delivery Receipt - Validity Period

Webhook format

Sample delivery receipt for outbound SMS

Requirements

Retry logic

Read Receipt - Validity Period

Webhook format

Sample delivery receipt for outbound message

WhatsApp Business App Messages

Sample WhatsApp Business App message webhook

General Error Codes

WhatsApp Error Codes

Viber Error Codes

HTTP Error Codes

API Response Property Values

SMS API, Messaging API