Errors

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 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.
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 and keep the same messageId correlation if you already received one.

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.

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.

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. Do not retry a 400 until you change the request.

After you send

HTTP 200 means the API accepted the message, not that the handset received it. Subscribe to webhooks for DELIVERED, FAILED, WhatsApp message_status, and RCS user replies.