Statuses & errors
The life of a campaign and of each message, and every error code.
Campaign statuses
in_reviewscheduledpreparingsendingcompletedpausedcancelledfailed| Status | Meaning |
|---|---|
draft | Not started: saved in the dashboard, or sent back from review (campaign.rejected). |
in_review | Waiting for the Mawgood team's approval (workspaces in review mode). |
scheduled | Waiting for scheduledAt. |
preparing | Checking recipients (opt-outs, caps, numbers) and queueing messages. |
sending | Messages are going out, at the campaign's pace. You get campaign.started. |
paused | Stopped for now; pauseReason says why. You get campaign.paused. |
completed | Every message was sent or skipped. You get campaign.completed. |
cancelled | Stopped by the API, the dashboard or the Mawgood team. You get campaign.cancelled. |
failed | Couldn't run, or every message failed at WhatsApp. You get campaign.failed. |
A campaign can be completed and then turn failed: it completes when the last message is handed
to WhatsApp, and fails if WhatsApp then refuses every one of them.
GET /campaigns/{id} returns the whole campaign:
{
"id": "cmp_9Xa4Lr",
"name": "Eid offer",
"status": "sending",
"pauseReason": null,
"reviewNote": null,
"source": "api",
"template": { "id": "tpl_8Kq2mZ", "name": "eid_offer", "language": "ar" },
"from": "num_3Fh7Ws",
"total": 900,
"pacing": { "mode": "steady", "overHours": 6 },
"counts": {
"pending": 400,
"queued": 20,
"sent": 120,
"delivered": 300,
"read": 40,
"failed": 5,
"skipped": 15,
"cancelled": 0,
"replied": 12
},
"scheduledAt": null,
"createdAt": "2026-11-20T10:00:00Z",
"launchedAt": "2026-11-20T10:00:02Z",
"completedAt": null
}Each message is counted once, by its current status; replied counts recipients who replied.
total is every row but the cancelled ones. source is api or dashboard: any campaign of the
workspace can be read.
Message statuses
pendingqueuedsentdeliveredreadfailedskippedcancelled| Status | Meaning |
|---|---|
pending | Accepted, not checked yet. |
queued | Checked and waiting for its turn. |
sent | Handed to WhatsApp. |
delivered | On the customer's phone. |
read | Opened (only when the customer has read receipts on). |
failed | WhatsApp refused it. error has Meta's code and title. |
skipped | Not sent because of a rule; skipReason says which. Costs nothing. |
cancelled | The campaign was cancelled before this message went out. |
error.explanation is always null for now. GET /campaigns/{id}/recipients lists the messages in
the order you gave them, 100 a page by default (limit up to 500, status to filter, cursor
for the next page), each with your externalId and the name you sent.
A reply sets repliedAt on the recipient (the status stays read or delivered) and fires
message.replied.
Statuses can skip steps
WhatsApp doesn't always report every step, and reports can arrive out of order. A message can go
from sent straight to read. Use the timestamps (sentAt, deliveredAt, readAt) and never
move a status backwards.
Errors
Every error has the same envelope:
{
"error": {
"code": "template_not_approved",
"message": "Template order_shipped (ar) is not approved.",
"details": { "template": "order_shipped" }
}
}Branch on code; message is for people and may change. details is optional.
| HTTP | code | What to do |
|---|---|---|
| 400 | validation_failed | The body isn't valid JSON. |
| 400 | body_aborted | The body was cut off before it ended. Send it again. |
| 401 | invalid_api_key | Check the key and the Authorization: Bearer header. |
| 402 | plan_required | Subscribe the workspace to a paid plan. |
| 403 | insufficient_scope | Use a key with the scope (details.missing). |
| 403 | publishable_key_not_allowed | Use a secret key (mwg_sk_…). |
| 403 | workspace_unavailable | The workspace is suspended or being closed. Contact Mawgood. |
| 403 | campaigns_off | Campaigns are off for this workspace. |
| 403 | test_key_cannot_send | The request is valid; send it with a live key. |
| 404 | not_found | Check the id. Ids belong to one workspace. |
| 404 | template_not_found | No template with this id, or this name and language. |
| 404 | number_not_found | from isn't one of your WhatsApp numbers. |
| 409 | idempotency_conflict | This Idempotency-Key was used with another body. Use a new key. |
| 409 | idempotency_in_progress | The first request with this key is still running. Retry shortly. |
| 409 | wrong_state | The campaign can't do this now (cancel after it ended). |
| 413 | too_large | The body is over 8 MB. Split the list. |
| 415 | unsupported_media_type | Send the body with Content-Type: application/json. |
| 422 | validation_failed | Fix the request (or add Idempotency-Key); details points at the field. |
| 422 | missing_variables | Give every recipient all the template's values. |
| 422 | template_not_approved | Pick an approved template (GET /templates?status=approved). |
| 422 | template_not_on_number | The template isn't approved on that number (or on any connected one). |
| 422 | template_not_supported | The API can't send this kind of template (details.reason). |
| 422 | number_required | Several numbers can send it: pass from (details.numbers). |
| 422 | no_valid_recipients | No recipient has a valid WhatsApp number (details.skipped). |
| 422 | split_required | Too many recipients even at the slowest pacing. Split the list. |
| 422 | not_ready | Something must be fixed first (details.blockers: no_number, quality…). |
| 429 | rate_limited | Over 600 requests a minute with this key. Wait Retry-After seconds. |
| 500 | internal | Our side. Retry with backoff and the same Idempotency-Key. |
Retry only 429, 409 idempotency_in_progress and 5xx errors, with exponential backoff and the
same Idempotency-Key. Any other 4xx will fail the same way until you change the request.