Errors

Two things to check on every response: the HTTP status, and accepted on a send. A refused message returns 200, so status alone is not enough.

Shape

{
  "success": false,
  "message": "Your wallet balance is too low to send this message. Add funds and try again."
}

message is written to be shown to a person as-is. It never contains a stack trace, an internal identifier or anything about our infrastructure.

Status codes

Retry only where the table says so.
Field	Type	Description
`200`	processed	The request was handled. On a send, check `accepted`: a message the network refused also returns 200.
`400`	do not retry	Malformed body, missing field, wrong number of variables, or a template, sender ID or chain that is not ready. Fix the cause; retrying the same request produces the same answer.
`401`	do not retry	The API key was not accepted: wrong, malformed or revoked. All three look identical on purpose.
`402`	retry after topping up	Wallet too low. Nothing was sent and nothing was charged.
`403`	do not retry	Valid credential, wrong place. An API key on a panel-only endpoint: registering entities, sender IDs or templates, or creating keys.
`404`	do not retry	No such template, or no such message on your account. A message id belonging to someone else looks the same as one that does not exist.
`429`	retry after a pause	Rate limited. Back off briefly and continue; do not retry immediately in a loop.
`500`	retry	Something failed on our side. Retry with backoff.
`503`	retry	Sending is temporarily unavailable. Nothing was charged.

Refusals that arrive as 400

These are setup problems rather than request problems, and each names what to fix:

Field	Type	Description
`Template not approved`	wait or fix	It is still in review, or was rejected. Check the Templates page in the panel.
`Sender ID not approved`	wait or fix	Same, on the Sender IDs page.
`DLT chain not verified`	fix	Our telemarketer ID must be declared on your DLT portal against the entity. This one blocks every message on the account, not just this request. See the manual.
`Wrong number of variables`	fix	Count the {#var#} markers in the approved body and supply exactly that many, in order.

Rejections on a 200

When accepted is false, the message reached the network and was refused. message says what a customer can do about it, and there are only two shapes:

The number is the problem. "That mobile number does not look valid." Check it; retrying the same number will not help.
The problem is on our side. "This message could not be sent right now and has not been charged." Nothing you can fix, nothing charged, and our team is notified. Retrying shortly is reasonable; retrying in a tight loop is not.

Writing retry logic

Branch on the status class first
4xx other than 429 and 402 means stop. 429, 500 and 503 mean retry.
Then branch on accepted
A 200 with accepted: false is a settled outcome for that message. Retrying sends a second message rather than fixing the first.
Back off exponentially, with a cap
A fixed one-second retry from many workers at once is the same as no retry logic at all.
Give up and record
After a few attempts, store the message_id if you have one and move on. A human looking at a list of failed ids is more useful than a queue retrying forever.

Errors

Shape#

Status codes#

Refusals that arrive as 400#

Rejections on a 200#

Writing retry logic#

Shape

Status codes

Refusals that arrive as 400

Rejections on a 200

Writing retry logic