Errors reference

Every RCS gateway rejection, whether at send time (sync response) or asynchronously via a delivery webhook, is translated to a customer-facing shape:

{
  "success":   false,
  "message":   "Recipient has opted out of RCS",
  "detail":    "Remove them from the list, don't retry.",
  "category":  "recipient",
  "retryable": false
}

message, one-line "what went wrong" title.
detail, actionable "how to fix" line.
category, colour-code bucket: content, media, recipient, config, quota, gateway, unknown.
retryable, whether an automatic retry has any chance. When true, the API will re-queue the send automatically.
message_id, only when a send could not be confirmed: the network did not answer in time, or the connection broke after the message may have left. It can still arrive. If it does, its delivery webhook carries this message_id and the message is charged then; if it never arrives, nothing is charged. retryable is false here, because sending it again could reach the recipient twice.

The same friendly title lands in failure_reason on the broadcast targets endpoint so a broadcast's Targets view shows the resolution hint directly.

Error categories

Category	Meaning	Action
`content`	Template or payload violates a rule	Edit the template
`media`	Media URL or size problem	Re-upload the media
`recipient`	Something about this phone	Skip or remove the phone
`config`	Account / agent not fully set up	Contact support
`quota`	Rate limit or monthly cap	Slow down or wait
`gateway`	Transient gateway issue	Auto-retried

Common errors and how to fix them

Content

Message	Fix
Message text is too long	Trim to ≤ 2000 characters.
Card title is too long	Trim to ≤ 200 characters (recommend ≤ 40).
Card description is too long	Trim to ≤ 2000 characters (recommend ≤ 112).
Too many buttons on the card	Max 4 buttons per card (recommend ≤ 2).
Carousel needs 2 to 10 cards	Add or remove cards.
A URL in the template isn't valid	Every link must be `https://` and publicly reachable.
`expireTime` is invalid	Use an ISO-8601 UTC timestamp, max 15 days out.
`ttl` is invalid	Digit-string ending in `"s"` (e.g. `"50s"`), max 15 days.
Both `ttl` and `expireTime` were set	Pick one.

Media

Message	Fix
Image is too large	Standalone ≤ 2 MB, carousel ≤ 1 MB. Compress.
Video is too large	Standalone ≤ 10 MB, carousel ≤ 5 MB. Re-encode.
Video thumbnail is too large	Thumbnail ≤ 40 KB. Export smaller JPEG.
Unsupported file type	Only jpeg/jpg/png/gif, mp4/mpeg/webm, and pdf.
Media not accessible	Re-upload via the panel so it lands in our public storage.

Recipient

Message	Fix
Recipient has opted out of RCS	Remove them from the list, don't retry.
Recipient phone number is not in the expected format	Use E.164 (e.g. `+919876543210`).
RCS not enabled on this recipient	Their device or carrier doesn't support RCS.
No recipient on the send	Attach at least one phone.

Config

Message	Fix
RCS agent still launching	Retry in a few minutes, usually finishes within 5.
RCS agent ID is missing or wrong	Contact support so we can re-issue.
RCS account is inactive	Contact support.

Quota

Message	Fix
Sending faster than your TPS allows	Lower broadcast speed in Settings, or contact support to raise.
Monthly send limit hit for this recipient	Try again after the 1st of next month.

Gateway (auto-retried)

Message	What we do
Gateway hiccup	Auto-retry, no action needed.

Structural validator errors (at template create)

The /rcs/templates endpoint also enforces every rule above at submit time (see Templates). A validator rejection returns:

{
  "success":  false,
  "message":  "Template violates RCS limits. Fix the issues below and resubmit",
  "errors":   ["…", "…"],
  "warnings": ["…"]
}

Hard errors block the submit; warnings are informational (recommendations that hurt rendering but don't block sending).

API-level error codes

Non-gateway errors from our endpoints return a stable code field alongside the message, so your client can programmatically react to specific conditions:

{
  "success": false,
  "code":    "no_active_bot",
  "message": "Please activate an RCS bot before creating templates. Go to Apply for a bot."
}

`code`	Where it fires	Meaning + fix
`no_active_bot`	template create, `send`, `send-template`, broadcasts	Your account has no bot in `active` status. Provision one from Settings → Bots, or wait for admin approval.
`unsupported_provider`	`check-reachability`	HTTP 400. The bot is not set up to check numbers yet. Contact support.
`bot_missing_credentials`	`check-reachability`	HTTP 400. The bot is not set up to check numbers yet. Contact support.
`bot_cannot_check`	`check-reachability`	HTTP 400. The bot you passed does not support number checks. Pick an active bot that does. See Contact lists.
`no_check_bot`	`check-reachability`	HTTP 400. No bot was passed and your account has no active bot that supports number checks, so no check can run. Broadcasts still go to every number that has not opted out, apart from any an earlier finished check found unreachable.
`check_busy`	`check-reachability` (panel only)	HTTP 503. Your account has no bot that supports number checks, so we run the check for you, and checks are busy right now. The message is `Number checks are busy right now. Try again in a few minutes.` Nothing started. Try again in a few minutes. API calls never get it.
`check_in_progress`	`check-reachability`, remove unreachable, `reachable.csv`, `create-reachable-list`	HTTP 409. A reachability check is already running for this list. On `check-reachability` the response echoes the current progress. Wait for it to finish, then call again.
`no_finished_check`	remove unreachable, `reachable.csv`, `create-reachable-list`	HTTP 409. No finished check stands behind the list's answers: it was never checked, its last check failed or stopped, or it was made with a bot that does not support number checks. Run a check, then call again. See Contact lists.
`no_reachable_recipients`	broadcast create, start	HTTP 400. The broadcast's `audience` reaches nobody on the list. `reason` says why: `empty_list`, `all_unreachable`, `all_opted_out` or `none_cannot_get`. `all_unreachable` (`audience: "rcs"`) can come from a check made with any of your bots, and applies to a broadcast from any of them. It is also the reason when every number left failed as not on RCS with this bot in the last 30 days. `none_cannot_get` (`audience: "not_rcs"`) means no number on the list is marked unreachable. Pick another list or another `audience`. See Broadcasts.
`invalid_audience`	broadcast create, recurring create/update	HTTP 400. `audience` must be `rcs`, `not_rcs` or `all`. Leave it out for `rcs`. See Broadcasts.
`spend_limit_reached`	broadcast create, start, send-now	HTTP 409. Today's daily spend limit is reached. The body carries `daily_limit`, `today_spend` and `resets_at`. Create and Start still accept a broadcast scheduled for a later day. Wait until `resets_at`, or ask the owner to raise the limit. See Broadcasts.
`broadcasts_unavailable`	broadcast list	HTTP 503. The list could not be read right now. Try again.
`reasons_unavailable`	`failure-reasons`	HTTP 503. `Could not load the failure reasons right now. Try again in a moment.`
`taps_unavailable`	`button-taps`	HTTP 503. `Could not load the button taps right now. Try again in a moment.`
`targets_unavailable`	targets, retarget, `remove-not-on-rcs`	HTTP 503. The broadcast's recipients could not be read right now. Nothing was changed. Try again.
`list_not_found`	`remove-not-on-rcs`	HTTP 404. The list the broadcast used was deleted.
`not_on_rcs_unconfirmed`	`remove-not-on-rcs`	HTTP 409. Nothing on the broadcast was delivered and many numbers failed as not on RCS, so the bot may not be live yet. Nothing is removed. Contact support. See Broadcasts.
`no_recipients`	retarget	HTTP 400. Nobody on the broadcast matched the subset. No list is made. `dropped_optout_count` says how many matched but are on your opt-out list.
`invalid_limit`	`PUT /spend-limit`	HTTP 400. The daily limit must be from 1 to 10000000 rupees, or `null` / `0` to turn it off.
`spend_limit_unavailable`	`GET /spend-limit`	HTTP 500. The limit could not be read. Try again.
`save_failed`	`PUT /spend-limit`	HTTP 500. The limit could not be saved. Nothing changed. Try again.
`rcs_not_active`	`send`, `send-template`	RCS is not enabled for your account, no agent credentials on file. Apply at Settings → Bots.
`template_not_approved`	`send-template`	Referenced template's `status` is not `approved` (either `pending` or `rejected`). Only approved templates can be sent.
`insufficient_balance`	`send`, `send-template`, broadcast create	Wallet balance < `rcs_per_msg_price`. Top up from Settings → Wallet.
`bot_not_promotional`	broadcast create/start/send-now, retarget, recurring create/update/resume	The bot is registered with the carrier as Transactional or OTP and cannot run bulk sends. Use `POST /rcs/messages/send` for this bot, or pick one where `can_broadcast` is `true`.

Multi-bot 409 conflicts

POST /rcs/apply runs a uniqueness gate on company_gstin and brand_website. A conflict with a different account returns HTTP 409 with a field key so your client can render the error under the exact input:

Field	Message
`gstin`	This GSTIN is already registered under another RCS account. Contact support with proof of ownership if this is incorrect.
`brand_website`	This brand website is already registered under another RCS account. Contact support with proof of ownership if this is incorrect.

Reusing your own GSTIN or brand website across multi-brand submissions on the same account is allowed and never triggers this conflict.

Broadcast / send with wrong bot

If bot_id isn't owned by the calling account or isn't in active status, the endpoint returns HTTP 403:

{
  "success": false,
  "code":    "bot_not_active",
  "message": "This bot is not active. Wait for admin activation or pick another bot."
}

When the status is specifically suspended, the sibling GET /rcs/bots/:bot_id response includes a suspend_reason field so the panel can render it inline, see Bots reference.

Broadcast on a non-promotional bot

A bot registered Transactional or OTP is provisioned for one-per-event traffic. Every bulk endpoint refuses it with HTTP 403:

{
  "success":      false,
  "code":         "bot_not_promotional",
  "message":      "\"Acme Orders\" is registered with the carrier as a Transactional bot, so it cannot run broadcasts. …",
  "bot_use_case": "transactional",
  "use_instead":  "POST /api/v1/rcs/messages/send"
}

This is not recoverable by retrying, topping up, or waiting, the bot's carrier registration has to change, which only support can do. The fix in your code is to route this bot's traffic through send message, which it can use without restriction.

Filter with the can_broadcast flag on GET /rcs/bots to avoid the error entirely. A bot whose registration was never recorded returns can_broadcast: true and is not refused.

Team member gates

Migration 283 introduced team members with per-bot scoping. These codes surface when a non-owner or scope-restricted caller hits an endpoint they're not authorised for. See the Team members reference for the role matrix.

Code	HTTP	When
`not_owner`	403	A non-owner hit an owner-only endpoint (billing, wallet, invoices, apply-for-bot, team management, bot-credential edits).
`not_operator`	403	A viewer hit a mutation endpoint (create/delete/send).
`bot_not_assigned`	403	Any role hit an endpoint targeting a bot outside their `bots` JWT claim.
`no_bots_assigned`	403	A member has zero bot assignments, the panel should surface "ask the owner for access".
`email_already_member`	409	Owner tried to invite an email that's already an active member of their account.
`invite_not_found`	404	Invite token doesn't resolve, link is invalid or already accepted.
`invite_expired`	410	Invite is past its 7-day TTL.

Opt-out list

Code	HTTP	When
`outside_promotional_window`	403	The bot is registered Promotional and it is outside 07:00 to 22:00 IST. Carried on `POST /rcs/messages/send` and on broadcast start. The response includes `opens_at`, an ISO-8601 timestamp of the next moment the bot may send, so a client can wait rather than poll. Transactional and OTP bots never see this. A broadcast already running when the window closes is not failed: it moves to `scheduled` for the next opening and resumes by itself.
`recipient_opted_out`	403	The recipient phone is on the caller's opt-out list. `POST /rcs/messages/send` and every per-message send-path emit this before anything is sent. Remove the phone via `DELETE /rcs/opt-out/{phone}` if the block was accidental.

Test send

Code	HTTP	When
`no_test_phone`	400	`POST /rcs/test-send` was called before the operator saved a `test_phone_number` or the account `phone` is empty. Set one in Settings.
`bot_not_active`	403	The target bot is not `active`. On a test send that means `pending` / `suspended` / `rejected`; on any broadcast path it also includes `processing`, which may test-send but never broadcast.
`bot_not_provisioned`	403	The bot has no `agent_id` / `agent_key`, support must provision it first.

Reports

Code	HTTP	When
`invalid_date_range`	400	`to < from` or window > 90 days on `/rcs/reports/summary` or `/rcs/reports/export`.
`too_many_exports_queued`	429	More than 5 exports concurrently `queued` or `running` on the same account.
`export_not_found`	404	Unknown `export_id` or the row expired (7-day retention).

Errors reference

Error categories#

Common errors and how to fix them#

Content#

Media#

Recipient#

Config#

Quota#

Gateway (auto-retried)#

Structural validator errors (at template create)#

API-level error codes#

Multi-bot 409 conflicts#

Broadcast / send with wrong bot#

Broadcast on a non-promotional bot#

Team member gates#

Opt-out list#

Test send#

Reports#