API Errors and HTTP Status Codes
Use the HTTP status first, then the JSON error and message fields. Successful sends still return a body — error is null and message describes the result.
HTTP 200 on send means the API accepted the job. It does not mean the handset got the message. Delivery is webhooks and channel reports.
HTTP status codes
- Name
200- Description
The HTTP call was accepted. Read the JSON anyway: some business failures are returned with a message in the body (
errornotnull, or emptydata).
- Name
400- Description
The request was malformed or failed validation (missing fields, invalid numbers, unknown template).
- Name
500- Description
An unexpected error occurred on the server. Retry with backoff. If you already have a
messageId, do not create a second campaign for the same user action until you know the first job failed.
Do not retry a 400 until you change the request. Retry 500 with exponential backoff.
Successful send body
Channel send APIs return a batch wrapper. error is null when the request was accepted.
Success
{
"id": "58d63c02-XXXX-XXXX-XXXX-XXXXbb39453",
"data": [
{
"recipient": "91XXXXXXXXXX",
"messageId": "58d63c02-XXXXX-XXXXX-XXXXX-XXXX9bb39453:1"
}
],
"totalCount": 1,
"message": "Message Sent Successfully!",
"error": null
}
Keep messageId. Delivery webhooks refer to the same id.
If every destination is blocklisted, some send APIs still return success with empty data and totalCount: 0. Those numbers were skipped, not billed.
Authentication failure
Error response
{
"error": true,
"message": "Api Key not found"
}
Check that the apikey header is present, has no extra quotes, and matches a key from the dashboard. See Authentication.
Validation and batch errors
WhatsApp Customize rejects the whole batch if any item is invalid. The message includes the item index, for example custom[1]: Invalid Template Name. Fix that item and resend the same payload — nothing in the batch is sent until every item is valid.
For other endpoints, read message and, when present, per-recipient objects inside data.
After you send
- Persist
id(campaign) anddata[].messageId. - Subscribe to the channel webhook. Event map.
- Treat later
DELIVERED/FAILED/ WhatsAppmessage_status/ RCS callbacks as the handset result. - Use channel Number report in the portal if you have no webhook yet.
Typical first-send issues
These are the usual reasons a first SMS, WhatsApp, or RCS send does not go out. Full lists live on each channel guide.
| Situation | What it usually means |
|---|---|
Missing / bad apikey | See Authentication |
| User or key disabled | Activate the account or generate a new key |
| Low wallet | Recharge from Account → Wallet |
Unknown sender / from / botId | Use an Approved sender, connected WhatsApp number, or RCS bot on this account |
| India SMS without DLT | PE ID on the sender and template ID on the template. What DLT is |
| WhatsApp template not Approved | Wait for Meta, or fix a rejection. Templates |
| Session WhatsApp outside 24 hours | Use a template. Session window |
| RCS device not capable | Capability check and/or Fallback |
| Blocked number | Skipped; may look like success with empty recipients |
| IP not on the key allowlist | Add the server IP on the key |
Next: Webhooks to learn delivery, or Recipes to copy a working send.