Skip to content

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 (error not null, or empty data).

  • 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

  1. Persist id (campaign) and data[].messageId.
  2. Subscribe to the channel webhook. Event map.
  3. Treat later DELIVERED / FAILED / WhatsApp message_status / RCS callbacks as the handset result.
  4. 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.

SituationWhat it usually means
Missing / bad apikeySee Authentication
User or key disabledActivate the account or generate a new key
Low walletRecharge from Account → Wallet
Unknown sender / from / botIdUse an Approved sender, connected WhatsApp number, or RCS bot on this account
India SMS without DLTPE ID on the sender and template ID on the template. What DLT is
WhatsApp template not ApprovedWait for Meta, or fix a rejection. Templates
Session WhatsApp outside 24 hoursUse a template. Session window
RCS device not capableCapability check and/or Fallback
Blocked numberSkipped; may look like success with empty recipients
IP not on the key allowlistAdd the server IP on the key

Next: Webhooks to learn delivery, or Recipes to copy a working send.

Was this page helpful?