RCS Operator Error Codes

A failed RCS message returns a code from one of three places, and knowing which one tells you who can fix it.

Range	Returned by	Who fixes it
`2`–`30`	Jio RCS platform	Usually the request, the agent, or the recipient’s RCS status
`4xx-A` … `5xx-M01`	Vi RCS platform	Same, with Vi’s own numbering
`4xxx`, `900xxx`	OneXtel platform — the message never left OneXtel	You, in your account or payload

Operator codes are operator-specific: the same numeric value means different things on Jio and Vi, and OneXtel surfaces them back to you unchanged. A 4xxx or 900xxx code means the message was stopped before any operator saw it, so it was never charged. These are distinct from the OneXtel API validation errors (API_Invalid_Auth_Key, API_Missing_Recipient, and so on) documented under Send messages. A request that passes OneXtel validation can still fail downstream with one of the codes below.

Every operator’s codes arrive in the same place. Jio, Vi and Airtel each use their own error schema upstream, but OneXtel normalises them into a single delivery notification callback: the code arrives as errCode, with error carrying its description. You do not need per-operator parsing — only the meaning of the code differs, which is what the tables below are for.

Retry guidance

Every code below is marked with whether re-sending the same message is worthwhile:

Value	Meaning
YES	Transient condition. Retry with backoff.
NO	Permanent for this message or account. Retrying will fail again — fix the request, the account, or the recipient’s status first.
ONCE	The operator does not define this case. Retry at most once, after a long delay.

Jio

Errors returned by the Jio RCS platform.

Error Code	Error Type	Description / Resolution	Retry Allowed
2	Bad Request	Request is not proper. Please provide valid JSON body.	NO
3	Unauthorized	Unauthorized.	YES
4	Forbidden	Assistant is not launched yet. Please launch the assistant before retrying again.	NO
5	User Not Found	RCS Disabled. Please enable RCS as a service.	NO
6	Too Many Requests	Max number of messages for the number/assistant exhausted. Try next month.	ONCE
7	Internal Server Error	Server connectivity error. Please retry after some time.	YES
9	Bot Rate Limit Exceeded	Account-level TPS limit exceeded. Retry with allowed TPS.	YES
11	Internal Server Error	Request timeout occurred. Please try after some time.	YES
12	Internal Server Error	Bad gateway error. Please try after some time.	YES
13	Internal Server Error	Service temporarily unavailable. Please try after some time.	YES
14	Internal Server Error	Similar to bad gateway error. Please try after some time.	YES
15	Invalid Message Expiry	One of the expiry fields is already set. Please try with suitable expiry fields.	NO
16	Invalid ExpireTime Value	Please try with suitable `expireTime`.	NO
17	Invalid TTL Format	TTL must be a digit string ending with `s`. Please try with suitable value.	NO
20	Internal Server Error	GetCapabilities failed. Please try after some time.	ONCE
21	Internal Server Error	SendMessage request failed. Please validate the message and try again.	YES
23	Operation Not Allowed	Account is inactive. Activate the account and try again.	NO
24	Operation Not Allowed	User has opted out.	NO
25	Internal Server Error	Assistant not ready yet.	ONCE
28	Too Many Requests	Account-level TPS exceeded. Please retry with lower rate.	YES
—	Too Many Requests	Default account TPS exceeded.	NO
30	Internal Server Error	Assistant initialization failed. Please re-create assistant and try again.	NO

“Assistant” is the Jio term for the RCS agent (sender profile). Codes 4, 25, and 30 all point at agent provisioning rather than the message itself — check the agent’s launch status in the RCS platform before retrying.

Jio does not use codes 8, 10, 18, 19, 22, 26, 27 or 29. Handle any code outside this table as a failure you cannot act on, and check the delivery report for the reason.

Vi (Vodafone Idea)

Errors returned by the Vi RCS platform. Codes combine the HTTP status with a suffix letter. The -M01 suffix indicates the error was passed through from Google’s RCS platform (MaaP) rather than raised by Vi.

Error Code	Error Message	HTTP Status Code	Retry Allowed
400-A	Template provided with insufficient params	400	NO
400-B	Template not approved	400	NO
400-C	Test template limit exceeded	400	ONCE
400-D	Template code with bot doesn’t exist	400	NO
400-E	Agent Not found	400	NO
400-F	Not a valid JSON message	400	NO
400-G	Message type not supported	400	NO
400-H	Invalid phone Number	400	NO
400-M01	400 error reason from Google Platform	400	ONCE
401-A	Unauthorized	401	YES
401-B	Invalid ClientId	401	YES
401-C	Invalid IP Address	401	YES
401-D	User not in conversation and provided message is not a template	401	NO
402-A	Low balance. Please recharge	402	NO
403-A	Bot not launched	403	NO
403-B	User opted out	403	NO
403-C	Bot blocked for spam	403	NO
403-D	Curfew hours	403	NO
404-A	RCS disabled	404	NO
409-M01	409 error reason from Google Platform	409	ONCE
429-A	Too many requests	429	YES
429-B	Test template limit exceeded	429	YES
429-M01	Too many requests error from Google platforms/MaaPs	429	YES
500-A	Internal server error	500	YES
502-A	Bad gateway	502	YES
502-M01	Timeout from Google MaaP	502	NO
503-A	Curfew hours	503	NO
504-A	Timeout	504	YES

401-C (Invalid IP Address) means the calling IP is not whitelisted. Retrying from the same IP will not help — whitelist the IP first, then retry.

Two pairs of Vi codes carry the same meaning: “Test template limit exceeded” arrives as either 400-C or 429-B, and “Curfew hours” as either 403-D or 503-A. Handle both codes in each pair.403-D is being retired in favour of 503-A, but a message can still return it. Keep handling it, and confirm with support before removing it from your own handling.

OneXtel platform

Returned when OneXtel stops the message before it reaches an operator. Nothing was sent and nothing was charged. These codes are the same across channels except where noted.

Payload and template

Code	Error Type	Details	Retry Allowed
4001	Invalid Template Name	The template name does not match one registered on the account.	NO
4002	Unsupported Field	`fileName` is not supported in this payload.	NO
4003	Unsupported Field	`fileId` is not supported in this payload.	NO
4004	Unsupported Field	`showLocation` is not supported in this payload.	NO
4005	Unsupported Field	`calendarAction` is not supported in this payload.	NO
4006	No Template For Bot	No template found for the `botId` supplied.	NO
4007	Invalid Custom Parameters	One or more custom parameters are not valid.	NO
4018	Invalid Payload Or Template	The payload or the template it references failed validation.	NO
4019	Provided Details Invalid	One or more supplied values are not valid for this account.	NO

Account and routing

Code	Error Type	Details	Retry Allowed
4010	Insufficient Credit	Not enough available credit to send.	NO
4013	User Opt-Out	The recipient has opted out.	NO
4017	Missing Provider	No provider is configured for this account or channel.	NO
4020	Invalid Key, Profile and Type Combination	The API key is not authorised for that sender profile and message type together.	NO
900117	Timeout	The platform timed out while processing the message.	YES
900122	Blacklisted	The recipient is on the account blacklist.	NO
900256	Third-Party Message Failed	A message submitted through a third-party integration failed on the platform.	ONCE

Expiry

Code	Error Type	Details	Retry Allowed
4009	TTL Expiration Revoked	The message expired and was revoked before delivery.	NO
4011	TTL Expiration Revoke Failed	The message expired but the revoke did not complete.	ONCE
4012	TTL Expiration Revoked	The message expired and was revoked before delivery.	NO

4009 and 4012 mean the same thing, and differ only in case (ttl_expiration_revoked and TTL_EXPIRATION_REVOKED). Handle both.

Frequency and category

Code	Error Type	Details	Retry Allowed
900115	Frequency Limit Reached	A configured send-frequency limit was hit.	YES
900118	Template Category Blocked	The template’s category is blocked for this account.	NO
900119	Template Category Changed	The template’s category changed after approval; resubmit it.	NO
900120	Monthly Frequency Limit Reached	The account’s monthly send limit was reached.	NO
900121	Daily Frequency Limit Reached	The account’s daily send limit was reached.	YES

900xxx codes are channel-specific. The same number means different things on different channels. 900118–900122 all mean something else on India SMS: 900118 is a blocked template category here but an encoding limit on SMS, and 900122 is a blacklisted recipient here but an expired account validity on SMS. Always interpret a platform code against the channel that produced it.

Send RCS messages — OneXtel API-level error codes
Send RCS template messages
WhatsApp error codes — Meta equivalents and the same platform codes

WhatsApp

RCS

SMS (India)

SMS (International)

OmniChannel

Verify

RCS Operator Error Codes

Retry guidance

Jio

Vi (Vodafone Idea)

OneXtel platform

Payload and template

Account and routing

Expiry

Frequency and category

​Retry guidance

​Jio

​Vi (Vodafone Idea)

​OneXtel platform

​Payload and template

​Account and routing

​Expiry

​Frequency and category

​Related

Retry guidance

Jio

Vi (Vodafone Idea)

OneXtel platform

Payload and template

Account and routing

Expiry

Frequency and category

Related