Delivery & errors
How a message moves from sent to delivered, what happens when it fails, automatic refunds, and how to read Meta error codes.
After you send, WhatsApp reports back on what happened. This page explains the delivery lifecycle, where to see it, how failures are handled, and the error codes you are most likely to meet.
The delivery lifecycle
A send returns a message record immediately with a status of pending. As WhatsApp processes it, the status advances:
| Status | Meaning | Billing |
|---|---|---|
pending | Accepted by Darkel, being handed to WhatsApp | Fee reserved |
sent | WhatsApp accepted the message | Fee charged |
delivered | Arrived on the recipient’s device | Fee charged |
read | The recipient opened it | Fee charged |
failed | Could not be delivered | Fee refunded automatically |
Not every message reaches read — a recipient may receive a message without opening it, and read receipts depend on their privacy settings. delivered is the dependable signal that it arrived.
Where to see status
The dashboard is the source of truth for status. Open WhatsApp → Messages to see every outbound and inbound message with its current state, searchable by number, template or text.
When you send through the API, the response gives you the message record (including its id and initial status) at the moment of sending. Keep the id if you want to cross-reference a message with what you see in the dashboard.
Inbound replies
If a customer replies to your message, the reply is captured and attributed to your workspace, and appears in your message history alongside what you sent.
Automatic refunds
A message is charged when it is accepted, then settled once Meta confirms how it was billed. A failed message is refunded in full, a message Meta does not bill (free) is refunded in full, and a message billed as a different type has the difference refunded or charged — all credited to your prepaid balance automatically, with the calculation in your billing history.
This makes retries safe and cheap: a failed attempt costs nothing in the end, so you can re-send to a corrected number without worrying about double charges.
Real-time notifications
Today, delivery status and replies live in the dashboard, and the send response gives you the initial record. The public API is send-focused — there is no polling endpoint or outbound webhook for status in the current version.
If your use case needs delivery receipts or inbound replies pushed to your own systems in real time, tell us what you need via Support — we want to hear it.
Common errors & what they mean
Errors from the Darkel API
These come back synchronously when you call the send endpoint:
| Status | Why | Fix |
|---|---|---|
401 | Bad or revoked API key | Check the X-Api-Key header; rotate if needed |
403 | WhatsApp is not enabled for this workspace | Enrol in WhatsApp under Billing |
400 — invalid recipient | to is not a valid E.164 number | Use full international format, e.g. +2348012345678 |
400 — sandbox recipient | You messaged a number that is not on the sandbox allow-list | Use an approved test number, or ask us to add one |
400 — insufficient balance | Your prepaid balance cannot cover the fee | Top up your balance |
400 — not set up | No WhatsApp number is connected for the workspace | Connect a number (or use a shared one) |
Errors from Meta (on failed delivery)
When WhatsApp accepts a message but it later fails, the failure carries a Meta error code. The ones you are most likely to see:
| Code | Meaning | What to do |
|---|---|---|
| 131042 | The WhatsApp Business Account has no active payment method with Meta | Add a payment method to your WABA in Meta Business settings |
| 131030 | Recipient is not allowed (e.g. not on the sandbox test list) | Add the number to your sandbox allow-list, or move to live |
| 131031 | The recipient number is blocked or deactivated | Use a different number |
| 1101 / token errors | Access has expired or is invalid | Reconnect your number via the dashboard |
Accepted but not delivered?
The classic “the send succeeded but nothing arrived” case is error 131042 — no payment method on the WhatsApp Business Account. On localhost without delivery tracking you may not see this at all, so always confirm against a real recipient and your message history.