Skip to Content
Developer docsBeta

Statuses & errors

The life of a campaign and of each message, and every error code.

Campaign statuses

in_reviewscheduledpreparingsendingcompleted
Can also end as, or pause at:pausedcancelledfailed
StatusMeaning
draftNot started: saved in the dashboard, or sent back from review (campaign.rejected).
in_reviewWaiting for the Mawgood team's approval (workspaces in review mode).
scheduledWaiting for scheduledAt.
preparingChecking recipients (opt-outs, caps, numbers) and queueing messages.
sendingMessages are going out, at the campaign's pace. You get campaign.started.
pausedStopped for now; pauseReason says why. You get campaign.paused.
completedEvery message was sent or skipped. You get campaign.completed.
cancelledStopped by the API, the dashboard or the Mawgood team. You get campaign.cancelled.
failedCouldn'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

pendingqueuedsentdeliveredread
Or ends as:failedskippedcancelled
StatusMeaning
pendingAccepted, not checked yet.
queuedChecked and waiting for its turn.
sentHanded to WhatsApp.
deliveredOn the customer's phone.
readOpened (only when the customer has read receipts on).
failedWhatsApp refused it. error has Meta's code and title.
skippedNot sent because of a rule; skipReason says which. Costs nothing.
cancelledThe 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.

HTTPcodeWhat to do
400validation_failedThe body isn't valid JSON.
400body_abortedThe body was cut off before it ended. Send it again.
401invalid_api_keyCheck the key and the Authorization: Bearer header.
402plan_requiredSubscribe the workspace to a paid plan.
403insufficient_scopeUse a key with the scope (details.missing).
403publishable_key_not_allowedUse a secret key (mwg_sk_…).
403workspace_unavailableThe workspace is suspended or being closed. Contact Mawgood.
403campaigns_offCampaigns are off for this workspace.
403test_key_cannot_sendThe request is valid; send it with a live key.
404not_foundCheck the id. Ids belong to one workspace.
404template_not_foundNo template with this id, or this name and language.
404number_not_foundfrom isn't one of your WhatsApp numbers.
409idempotency_conflictThis Idempotency-Key was used with another body. Use a new key.
409idempotency_in_progressThe first request with this key is still running. Retry shortly.
409wrong_stateThe campaign can't do this now (cancel after it ended).
413too_largeThe body is over 8 MB. Split the list.
415unsupported_media_typeSend the body with Content-Type: application/json.
422validation_failedFix the request (or add Idempotency-Key); details points at the field.
422missing_variablesGive every recipient all the template's values.
422template_not_approvedPick an approved template (GET /templates?status=approved).
422template_not_on_numberThe template isn't approved on that number (or on any connected one).
422template_not_supportedThe API can't send this kind of template (details.reason).
422number_requiredSeveral numbers can send it: pass from (details.numbers).
422no_valid_recipientsNo recipient has a valid WhatsApp number (details.skipped).
422split_requiredToo many recipients even at the slowest pacing. Split the list.
422not_readySomething must be fixed first (details.blockers: no_number, quality…).
429rate_limitedOver 600 requests a minute with this key. Wait Retry-After seconds.
500internalOur 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.

On this page